Images

Overview

An image is a "lightweight, standalone, executable package of software that includes everything needed to run an application: code, runtime, system tools, system libraries, and settings".

Control Plane offers its users their own hosted private image registry. Your application will be packaged and stored as an image and will be served by a Workload.

When configuring the source of the Workload's container image, you have the option of using either an external private/public image registries, such as Docker Hub, or the internal private image registry offered by the platform.

The CLI contains the functionality to build and push your application to your private image registry.

Benefits

The benefits of using your Org's private image registry are:

No Pull Secrets are required when configuring your workload.
Minimizes latency when pulling the image into your container.
Requires access permissions when pushing/pulling from outside the platform (e.g. using Docker push/pull).

Pull an Image

Refer to the Pull an Image guide for additional details.

Push an Image

Refer to the Push an Image guide for additional details.

Copy an image

Using the CLI, to copy an image from one org to another, execute the following command:

copy
cpln image copy IMAGE_NAME:TAG --org SOURCE_ORG --dest-org DESTINATION_ORG

Update an Image

Using the CLI, to update the image a container is pulling, execute the following command:

copy
cpln workload update WORKLOAD_NAME --set spec.containers.CONTAINER_NAME.image=IMAGE:TAG --gvc GVC_NAME --org ORG_NAME

NOTE: Use the convention //image/IMAGE:TAG to reference an image residing within the current Org's private repository.

Permissions

The permissions below are used to define policies together with one or more of the four principal types:

Permission	Description	Implies
create	Create new image. You can push if you can create images.	pull
delete	Delete
edit	Modify existing image (only tags can be changed)	view
manage	Full access	create, delete, edit, manage, pull, view
pull	Image can be pulled	view
view	Read-only access

Minimum Policy

Push

At a minimum, the create permission must be bound to the principal pushing an image to an org's private registry.

Using the console UI, follow these steps to create a least privileged policy which will allow a principal to push an image:

Click Policies in the left menu bar and click the New button at the top of the form.
Enter a policy name, select image from the Target Kind pulldown, and enable the Target All Images button. Click the Next button.
Click Add Binding.
Select the create permission. Select the principal type that will be pushing the image from the top menu bar and select the principal. Click Add.
Click Create.

The policy is now active and the principal has the ability to push images to the org's private registry.

Pull

At a minimum, the pull permission must be bound to a principal pulling an image from an org's private registry.

Unless the policy targets all images, a query must be created with the image names (without the tag) that the principal is allowed to pull. That query uses the property parameter and can only be created/updated using cpln apply or the CLI's cpln profile command.

Below is a sample JSON manifest used as input to cpln apply.

Notice that the property parameter is equal to repository.

Update the POLICY_NAME, ORG_NAME, USER_EMAIL, SERVICE_ACCOUNT_NAME, and IMAGE_NAME tokens.

The principalLinks can refer to a user or service account.

copy
{
  "kind": "policy",
  "name": "POLICY_NAME",
  "description": "",
  "tags": {},
  "origin": "default",
  "bindings": [
    {
      "permissions": [
        "pull"
      ],
      "principalLinks": [
        "/org/ORG_NAME/user/USER_EMAIL",
        "/org/ORG_NAME/serviceaccount/SERVICE_ACCOUNT_NAME"
      ]
    }
  ],
  "targetKind": "image",
  "targetLinks": [],
  "targetQuery": {
    "kind": "image",
    "fetch": "items",
    "spec": {
      "match": "all",
      "terms": [
        {
          "op": "=",
          "property": "repository",
          "value": "IMAGE_NAME"
        }
      ]
    }
  }
}

Once the policy is active, the principal will have the ability to pull images using any Docker compatible tool (e.g., docker pull ...).

Access Report

Displays the permissions granted to principals for the image.

CLI

To view the CLI documentation for images, click here.

placeholder

Contents