Deploy a container image

An image service runs a container image that someone else built. NebulaCtrl resolves the reference to a digest, so each release runs exactly the bytes it resolved. To build from source instead, see Deploy from Git.

Before you beginCopy Anchor Link

• A project with an environment that has a bound cluster. See Connect a cluster.
• For a private image, a registry credential, as described below.
• The deployer role or higher.

Add an imageCopy Anchor Link

1. Open the project. Right-click the canvas and select New service…, or press N.
2. In Add to canvas, select Container image.
3. Enter the Image, for example ghcr.io/acme/worker:1.4.0.
4. Enter an HTTP port for a web service, or leave it empty for a background worker.
5. Select Add image.

NebulaCtrl names the service after the image and stages its first deploy. Nothing runs until you apply the staged change set. In the staged bar, select Deploy N changes, or Request approval on a protected environment. See Change sets and approvals.

To run an image on a schedule, select Cron job in Add to canvas and enter a Name, the Image and a Schedule. For a registry credential or a push trigger, select Custom service and choose Image as the Source.

VerifyCopy Anchor Link

The service appears on the canvas, staged. After you apply the change set, its deployment becomes healthy. See Deployments for the stages it passes through.

Choose a tag or a digestCopy Anchor Link

A reference is resolved before the release is created:

• A bare name such as ghcr.io/acme/worker means the latest tag.
• A tag such as 1.4.0 is resolved to the digest it points to at that moment. Later pushes to the same tag change nothing until you deploy again.
• A digest, ghcr.io/acme/worker@sha256: followed by 64 lowercase hexadecimal characters, is used as written, with no lookup.

Resolution uses the linux/amd64 manifest and gives up after 15 seconds, so an image that is multi-architecture needs an amd64 entry. A reference that starts with a URL scheme, names a local path, or points at a registry that speaks plain HTTP is refused.

A deploy of latest runs whatever latest points to when you deploy.

Use a private registryCopy Anchor Link

A registry credential lets clusters pull a private image and lets NebulaCtrl resolve its tags.

1. Open Settings, then Integrations. Under Registries, select Add registry. This needs the admin role.
2. Enter the Host, for example ghcr.io, the Username, and the Password or token. The password is stored encrypted and never shown again.
3. Select Add registry.
4. Open the service's Settings tab, select Edit… under Source, and choose the credential under Registry credential.

The credential's host must equal the registry host of the image reference. Docker Hub references resolve to index.docker.io, so enter that host for them. An organization has one credential per host. To rotate a password, delete the credential and add it again.

Deploy a new versionCopy Anchor Link

• Deploy in the service's header resolves the saved tag again, or latest when none is saved, and creates a release from it.
• To deploy a particular tag or digest, select the caret beside Deploy, choose Deploy a different tag…, and enter the Tag or digest. Start with @sha256: to pin an exact digest. Select Deploy release.
• Redeploy on the active row releases the same image again against the newest configuration. It changes nothing about the image.

If the release needs downtime, the dialog says This release needs downtime and offers Accept downtime and deploy anyway.

Over the API, send POST /api/v1/services/{id}/releases with environmentId and a reference. Each call creates a release, and a protected environment still waits for an approval.

Deploy on every pushCopy Anchor Link

An image service can follow a Git repository without building anything. A service that does is a trigger-only service: a push to the repository starts a deploy of an image that your own CI builds, once that image's tag exists in the registry.

1. Open the service's Settings tab and select Edit… under Source.
2. Turn on Deploy on push.
3. Choose the Connection and the Repository whose pushes trigger the deploy.
4. Set the Tag template, a Go template over {{.ShortSHA}}, {{.SHA}} and {{.Branch}}. The default is {{.ShortSHA}}.
5. Select Save changes.

ShortSHA is the first 12 characters of the commit, SHA is the full commit, and Branch is the pushed branch name as written, so a branch feature/x gives a tag with a slash.

On a push to a branch that an environment tracks with auto-deploy on, NebulaCtrl waits for the rendered tag to appear in the registry. It checks every 20 seconds for up to 15 minutes. When the tag appears, it creates a release from the resolved digest, as a build would. If the tag does not appear, the build fails with tag TAG did not appear within 15m0s, and the commit gets a failure status. A newer push supersedes a wait that is still running. The service's Auto-deploy switch and the environment's Branch work as described in Deploy from Git.

If the image does not resolveCopy Anchor Link

The API answers 422. The message names the request field, reference or registryCredentialId, and then the reason:

Reason	Fix
HOST needs a registry credential with access to REPO	Add a registry credential for HOST, and choose it on the service
REPO does not exist on HOST	Check the repository name, and that the credential can see it
names HOST, which would use plain HTTP; configure that registry with HTTPS and try again	Serve the registry over HTTPS
is for X, not Y	Use a credential whose host equals the image's registry host

Next stepsCopy Anchor Link

• Git providers and registries covers connections and registry credentials in detail.
• Rollbacks and promotions covers returning to an earlier release.
• Variables covers configuring the container.