Skip to main content

GCP Cloud Agent Update

On GCP, the Fractal Cloud Agent runs as a Cloud Run service in the management project, with images stored in Artifact Registry. Updating the agent involves copying the new image to your Artifact Registry and deploying a new Cloud Run revision.

For common prerequisites (regctl installation, Fractal registry authentication), see the main guide.

Step 1 — Identify the Cloud Run service and Artifact Registry​

Locate the Cloud Run service and the Artifact Registry repository used by the Fractal Cloud Agent:

# List Cloud Run services in the management project
gcloud run services list --project <MANAGEMENT_PROJECT_ID>

# Get the current image for the agent service
gcloud run services describe <SERVICE_NAME> \
  --project <MANAGEMENT_PROJECT_ID> \
  --region <REGION> \
  --format 'value(spec.template.spec.containers[0].image)'

The image location will look like:

<REGION>-docker.pkg.dev/<MANAGEMENT_PROJECT_ID>/<REPOSITORY>/fractal.cloudagent.gcp.container:v<CURRENT_VERSION>

Step 2 — Authenticate with Artifact Registry​

gcloud auth login

gcloud auth configure-docker <REGION>-docker.pkg.dev

Also configure regctl to access your Artifact Registry:

GCP_TOKEN=$(gcloud auth print-access-token)
regctl registry login <REGION>-docker.pkg.dev -u oauth2accesstoken -p "$GCP_TOKEN"

Step 3 — Copy the new image to Artifact Registry​

Use regctl to copy the new agent image directly from the Fractal registry to your Artifact Registry:

regctl image copy \
  yanchware/fractal.cloudagent.gcp.container:<NEW_VERSION> \
  <REGION>-docker.pkg.dev/<MANAGEMENT_PROJECT_ID>/<REPOSITORY>/fractal.cloudagent.gcp.container:<NEW_VERSION>

Step 4 — Deploy a new Cloud Run revision​

Update the Cloud Run service to use the new image:

GCP Console:

  1. Go to the Cloud Console > Cloud Run.
  2. Select the Fractal Cloud Agent service.
  3. Click Edit & Deploy New Revision.
  4. Update the Container image URL to: 
    <REGION>-docker.pkg.dev/<MANAGEMENT_PROJECT_ID>/<REPOSITORY>/fractal.cloudagent.gcp.container:<NEW_VERSION>
  5. Click Deploy.

gcloud CLI:

gcloud run services update <SERVICE_NAME> \
  --project <MANAGEMENT_PROJECT_ID> \
  --region <REGION> \
  --image <REGION>-docker.pkg.dev/<MANAGEMENT_PROJECT_ID>/<REPOSITORY>/fractal.cloudagent.gcp.container:<NEW_VERSION>

Step 5 — Verify the update​

Check that the new revision is serving traffic:

gcloud run services describe <SERVICE_NAME> \
  --project <MANAGEMENT_PROJECT_ID> \
  --region <REGION> \
  --format 'value(spec.template.spec.containers[0].image)'

You can also check the service logs:

gcloud run services logs read <SERVICE_NAME> \
  --project <MANAGEMENT_PROJECT_ID> \
  --region <REGION> \
  --limit 50