Skip to content
NebulaCtrlInstall

Reference

View as Markdown

Registries API

7 operations. Every call needs a session cookie or an Authorization: Bearer nct_… token unless marked Public. Conventions, errors and scopes

GET/registries

List registries

Bring-your-own (external) and managed registries. Credentials are write-only and never returned.

Response 200 · OK · application/json
ListOutputBody3
  • RegistryView[] | nullrequired
Errors
  • 401Unauthorized
  • 403Forbidden
  • 500Internal Server Error

Errors are RFC 9457 application/problem+json with a stable code field.

POST/registries

Add an external registry

Adds a registry that takes basic auth (GHCR, Docker Hub, GitLab, Harbor, self-hosted). Credentials are sealed and write-only. ECR, GAR and ACR tokens that expire are not supported. The managed registry is set up with POST /platform-services (kind registry). Requires the admin scope.

ParameterInTypeDescription
Idempotency-KeyheaderstringClient-chosen key (<=255 chars). A retry with the same key replays the original response for 24 hours.
Request body · application/json · required
CreateInputBody2
  • hoststringrequired
    registry.example.com or registry.example.com:5000, without a scheme or path. ghcr.io, docker.io, registry.gitlab.com, a Harbor or self-hosted host.
  • namestringrequired
    Unique name in the team.
  • namespacestring
    The path between the host and the repository name: a GitHub user or organization, a Docker Hub namespace, a GitLab group/project. Images are pushed to <host>/<namespace>/<project>-<service>.
  • pullPasswordstring
    Write-only, never returned.
  • pullUsernamestring
    Optional read-only credential the target servers pull with. Without it they use the push credential.
  • pushPasswordstringrequired
    Write-only: a token or password, never returned.
  • pushUsernamestringrequired
    Write-only credential used to push images (basic auth). A registry without authentication takes any pair.
Response 201 · Created · application/json
RegistryView
  • createdAtstring (date-time)required
  • hasPullAuthbooleanrequired
    A separate read-only credential is set; targets pull with it. Otherwise they use the push credential.
  • hasPushAuthbooleanrequired
  • hoststringrequired
    registry.example.com[:port], no scheme.
  • idstringrequired
  • imageCountinteger (int64)required
    Live images.
  • inUsebooleanrequired
    A team, project or service setting uses it: it cannot be removed.
  • insecurebooleanrequired
    A loopback host: plain http is used.
  • kindenum: external | managedrequired
  • map of RegistryCheckrequired
    Result of the last check, by server id.
  • manageRetentionbooleanrequired
    NebulaCtrl deletes images that fall out of the rollback window (managed registries; opt-in for external).
  • RegistryManagedView
  • namestringrequired
  • namespacestringrequired
  • platformServiceIdstring
  • pullUsernamestring
  • pushUsernamestring
  • RegistryReferencesrequired
  • sizeBytesinteger (int64)required
    Space the live images take.
  • updatedAtstring (date-time)required
Errors
  • 401Unauthorized
  • 403Forbidden
  • 409Conflict
  • 422Unprocessable Entity
  • 500Internal Server Error

Errors are RFC 9457 application/problem+json with a stable code field.

GET/registries/{registryId}

Get a registry

ParameterInTypeDescription
registryIdrequiredpathstring
Response 200 · OK · application/json
RegistryView
  • createdAtstring (date-time)required
  • hasPullAuthbooleanrequired
    A separate read-only credential is set; targets pull with it. Otherwise they use the push credential.
  • hasPushAuthbooleanrequired
  • hoststringrequired
    registry.example.com[:port], no scheme.
  • idstringrequired
  • imageCountinteger (int64)required
    Live images.
  • inUsebooleanrequired
    A team, project or service setting uses it: it cannot be removed.
  • insecurebooleanrequired
    A loopback host: plain http is used.
  • kindenum: external | managedrequired
  • map of RegistryCheckrequired
    Result of the last check, by server id.
  • manageRetentionbooleanrequired
    NebulaCtrl deletes images that fall out of the rollback window (managed registries; opt-in for external).
  • RegistryManagedView
  • namestringrequired
  • namespacestringrequired
  • platformServiceIdstring
  • pullUsernamestring
  • pushUsernamestring
  • RegistryReferencesrequired
  • sizeBytesinteger (int64)required
    Space the live images take.
  • updatedAtstring (date-time)required
Errors
  • 401Unauthorized
  • 403Forbidden
  • 404Not Found
  • 422Unprocessable Entity
  • 500Internal Server Error

Errors are RFC 9457 application/problem+json with a stable code field.

PATCH/registries/{registryId}

Update a registry

Omitted fields stay as they are; an omitted password keeps the stored one. A managed registry can only be renamed and have its retention switched.

ParameterInTypeDescription
registryIdrequiredpathstring
Request body · application/json · required
PatchInputBody1
  • clearPullboolean
    Remove the read-only credential.
  • hoststring
  • manageRetentionboolean
    Let NebulaCtrl delete images that fall out of the rollback window. Managed registries only.
  • namestring
  • namespacestring
  • pullPasswordstring
    Omit to keep the stored password.
  • pullUsernamestring
  • pushPasswordstring
    Omit to keep the stored password.
  • pushUsernamestring
Response 200 · OK · application/json
RegistryView
  • createdAtstring (date-time)required
  • hasPullAuthbooleanrequired
    A separate read-only credential is set; targets pull with it. Otherwise they use the push credential.
  • hasPushAuthbooleanrequired
  • hoststringrequired
    registry.example.com[:port], no scheme.
  • idstringrequired
  • imageCountinteger (int64)required
    Live images.
  • inUsebooleanrequired
    A team, project or service setting uses it: it cannot be removed.
  • insecurebooleanrequired
    A loopback host: plain http is used.
  • kindenum: external | managedrequired
  • map of RegistryCheckrequired
    Result of the last check, by server id.
  • manageRetentionbooleanrequired
    NebulaCtrl deletes images that fall out of the rollback window (managed registries; opt-in for external).
  • RegistryManagedView
  • namestringrequired
  • namespacestringrequired
  • platformServiceIdstring
  • pullUsernamestring
  • pushUsernamestring
  • RegistryReferencesrequired
  • sizeBytesinteger (int64)required
    Space the live images take.
  • updatedAtstring (date-time)required
Errors
  • 401Unauthorized
  • 403Forbidden
  • 404Not Found
  • 409Conflict
  • 422Unprocessable Entity
  • 500Internal Server Error

Errors are RFC 9457 application/problem+json with a stable code field.

DELETE/registries/{registryId}

Delete an external registry

409 registry_in_use while a team default, a project or a service override uses it. A managed registry is removed with its platform service (409 managed_registry). Images already pushed stay in the registry.

ParameterInTypeDescription
registryIdrequiredpathstring
Response 204 · No Content

No body.

Errors
  • 401Unauthorized
  • 403Forbidden
  • 404Not Found
  • 409Conflictregistry_in_usemanaged_registry
  • 422Unprocessable Entity
  • 500Internal Server Error

Errors are RFC 9457 application/problem+json with a stable code field.

POST/registries/{registryId}/check

Test a registry from a server

The agent on the chosen server contacts the registry with the stored credentials and reports whether push and pull are accepted. Waits up to 25 seconds; if the agent has not answered by then the response has pending: true and the result appears in the registry's lastCheck.

ParameterInTypeDescription
registryIdrequiredpathstring
serverIdquerystringThe server whose agent runs the check. Builds and pulls reach the registry from servers, so this is the test that matters.
Response 200 · OK · application/json
RegistryCheck
  • atstring (date-time)required
  • errorstring
  • okbooleanrequired
  • pendingboolean
    The agent has not answered within the wait; read the registry again for the result.
  • pullbooleanrequired
  • pushbooleanrequired
  • serverIdstring
Errors
  • 401Unauthorized
  • 403Forbidden
  • 404Not Found
  • 409Conflict
  • 422Unprocessable Entity
  • 500Internal Server Error

Errors are RFC 9457 application/problem+json with a stable code field.

GET/registries/{registryId}/images

List the images pushed to a registry

Newest first. live images are inside the rollback window, expired ones are outside it (a managed registry deletes them at the next sweep), deleted ones are gone.

ParameterInTypeDescription
registryIdrequiredpathstring
statequeryenum: live | expired | deletedOnly images in this state.
limitqueryinteger (int64)Page size (default 50).
cursorquerystring
Response 200 · OK · application/json
RegistryImagePage
  • RegistryImageView[] | nullrequired
  • nextCursorstring
Errors
  • 400Bad Request
  • 401Unauthorized
  • 403Forbidden
  • 404Not Found
  • 422Unprocessable Entity
  • 500Internal Server Error

Errors are RFC 9457 application/problem+json with a stable code field.