Pull private images with a registry
Let kosem sign in to your container registry, with a token or with no key on Artifact Registry and ECR, so that agents' environments can run private images.
Let kosem pull private images for your projects' environments, such as ghcr.io/acme/devbox:1, by signing in to their registry. No environment ever sees the token or credentials. Your organization's registry is set up once and shared with projects: to create one, you need Owner, Editor or Environment Admin on the organization, and to share it, Owner. A project's own registry is for that project alone: you need Owner, Editor or Environment Admin on the project.
Create a registry that signs in with a token
You need a token that can read the images, such as a GitHub personal access token with read:packages, and the username it belongs to.
- In your organization, click Environments, and then Registries.
- Click New registry.
- Under Where are your images?, select the registry, such as GitHub or Docker Hub. Or paste an image into Image or registry (optional) to fill in the rest.
- Check what it Covers images under, such as
ghcr.io/acme. - Enter the Username, and under Secret, select a secret of your organization that holds the token, or paste the token into New token.
- Click Create registry.
kosem checks the token as it saves the registry. A token you paste is kept as a new secret of your organization, named after the registry.
Create a registry that signs in without a key
On Google Artifact Registry and Amazon ECR, your cloud can trust kosem's identity token for the registry, so that you keep no key.
- In your organization, click Environments, then Registries, then New registry.
- Select Google Artifact Registry, and enter its Location, Project ID, Repository (optional) and Project number. Or select Amazon ECR, and enter its Account ID and Region.
- Click Create registry.
- On the registry's Sign-in tab, run the commands of each step in a terminal signed in to your cloud. One script has them all, and can run again safely. Terraform has the same as Terraform.
- Click Check sign-in.
The check shows each step, so a refusal says what to fix. A new trust can take a few minutes to apply: if your cloud refuses at first, wait and check again.
Share it with projects
A new registry is shared with no project.
- On the registry's page, click the Sharing tab.
- Select All projects, or Selected projects and select them.
- Click Save.
From then on, environments of those projects pull the images it covers with it. kosem chooses the registry with the longest prefix that covers an image, such as ghcr.io/acme over ghcr.io.
Create a project's own registry
For a registry only one project needs, such as a team's own account, create it in the project.
- In your project, click Environments, and then Registries.
- Click New registry, and follow the steps above. A token is a secret of the project, and a pasted one is kept as a new secret of the project.
The project's environments pull with it, and with your organization's registries shared with the project. Of two with the same prefix, the project's own wins. It isn't shared with other projects.
If the page says a policy keeps projects from adding registries of their own, your organization turned on Turn off projects' own registries. Registries the project added before keep working; request one instead.
On Google Artifact Registry, the workload identity provider's condition, assertion.org == '…', takes your organization's registries and its projects' own alike, so one provider serves them all. A provider set up before projects had registries of their own took only the organization's: widen its condition to the one the setup shows now, or create another provider.
Request a registry for your project
If you can't create registries, ask your organization's Owners for one.
- In your project, click Environments, and then Registries.
- Click Request a registry.
- Enter the Image or address, such as
ghcr.io/acme/devbox:1, and click Send request.
Owners see the request on the organization's Registries page. They click Approve and select a registry that covers it, which shares it with your project, or Decline. If none covers it yet, they create one first.
Check why an image doesn't pull
When an environment can't pull its image, its page says why, and links to the project's registries.
- Open the registry under Environments › Registries, in your organization, or in the project for its own.
- On its Sign-in tab, enter the image in Image to try (optional), and click Check sign-in.
The check says whether kosem can sign in, and whether it can read that image.
Use the API
Set your API key (Call the API), your organization's ID and the secret's ID, then create a registry shared with every project:
export KOSEM_API_KEY='kosem_sk_…'
export KOSEM_ORG='org_01m5r8w2k3e9vbt6g0d4x7qz1h'
export KOSEM_SECRET='sec_01m5rd7wq3e9vbt6g0d4x7qz1p'
curl -s -X POST "https://api.kosem.ai/v1/organizations/$KOSEM_ORG/registries" \
-H "Authorization: Bearer $KOSEM_API_KEY" \
-H "Content-Type: application/json" \
-d "{\"prefix\": \"ghcr.io/acme\", \"token\": {\"username\": \"acme-bot\", \"secret\": \"organizations/$KOSEM_ORG/secrets/$KOSEM_SECRET\"}, \"availability\": {\"allProjects\": true, \"projects\": []}}"Keep the registry's ID from the response, then verify its sign-in with an image to try:
export KOSEM_REGISTRY='reg_01m5rg4xq2e9vbt6g0d4x7qz1r'
curl -s -X POST "https://api.kosem.ai/v1/organizations/$KOSEM_ORG/registries/$KOSEM_REGISTRY/verify" \
-H "Authorization: Bearer $KOSEM_API_KEY" \
-H "Content-Type: application/json" \
-d '{"image": "ghcr.io/acme/devbox:1"}'A project's own registry is created the same way at /v1/projects/$KOSEM_PROJECT/registries, with a secret of the project, and without availability.
The registry it answers with has a verification with each step and what it found:
{
"prefix": "ghcr.io/acme",
"state": "ACTIVE",
"verification": {
"steps": [
{ "step": "SIGN_IN", "state": "PASSED" },
{ "step": "READ", "state": "PASSED" }
]
}
}A refused token shows as "state": "FAILED" on SIGN_IN, with what the registry said in said, and READ as NOT_RUN. A registry that signs in without a key checks TRUST and ACCESS in its cloud first.