Skip to main content

OCI Cloud Agent Update

On OCI, the Fractal Cloud Agent runs as a Container Instance in the management compartment, with images stored in the OCI Container Registry (OCIR). Updating the agent involves copying the new image to OCIR and redeploying the container instance.

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

Availability

OCI Cloud Agent updates are currently available for enterprise customers only.

Step 1 — Identify the Container Instance and OCIR repository​

Locate the Container Instance used by the Fractal Cloud Agent in the management compartment:

# List container instances in the management compartment
oci container-instances container-instance list \
  --compartment-id <MANAGEMENT_COMPARTMENT_ID>

Find the current image reference. It will look like:

<REGION_KEY>.ocir.io/<TENANCY_NAMESPACE>/fractalcloud/fractal.cloudagent.oci.container:v<CURRENT_VERSION>

Step 2 — Authenticate with OCIR​

Generate an auth token in the OCI Console (Identity > Users > Auth Tokens), then log in:

docker login <REGION_KEY>.ocir.io -u '<TENANCY_NAMESPACE>/oracleidentitycloudservice/<USERNAME>'

When prompted, enter your auth token as the password.

Also configure regctl:

regctl registry login <REGION_KEY>.ocir.io \
  -u '<TENANCY_NAMESPACE>/oracleidentitycloudservice/<USERNAME>' \
  -p '<AUTH_TOKEN>'

Step 3 — Copy the new image to OCIR​

regctl image copy \
  yanchware/fractal.cloudagent.oci.container:<NEW_VERSION> \
  <REGION_KEY>.ocir.io/<TENANCY_NAMESPACE>/fractalcloud/fractal.cloudagent.oci.container:<NEW_VERSION>

Step 4 — Redeploy the Container Instance​

OCI Container Instances are immutable — you cannot update the image in place. You need to create a new container instance with the updated image and then delete the old one.

OCI Console:

  1. Go to Developer Services > Container Instances.
  2. Select the Fractal Cloud Agent container instance.
  3. Note down all configuration details (shape, networking, environment variables, etc.).
  4. Create a new container instance with the same configuration but the updated image tag.
  5. Once the new instance is running and healthy, terminate the old instance.

OCI CLI:

# Get the current container instance details
oci container-instances container-instance get \
  --container-instance-id <CONTAINER_INSTANCE_ID> > instance-config.json

# Create a new container instance with the updated image
# (edit instance-config.json to update the image URI, then use it as input)
oci container-instances container-instance create \
  --from-json file://instance-config.json

# After verifying the new instance is healthy, delete the old one
oci container-instances container-instance delete \
  --container-instance-id <OLD_CONTAINER_INSTANCE_ID>

Step 5 — Verify the update​

oci container-instances container-instance get \
  --container-instance-id <NEW_CONTAINER_INSTANCE_ID> \
  --query 'data."lifecycle-state"'

Confirm the state is ACTIVE and the agent is reporting to the Fractal Cloud control plane.