OCIRegistry

An OCI registry as a source. In convoy v0.9.0, convoy pulls only Helm chart artifacts from it.

An OCIRegistry is an OCI registry, for example oci://ghcr.io/stefanprodan/charts. Each Release selects the artifact and the version in spec.source.ociRegistry.artifact.


API group	`source.convoy.kumodo.io/v1alpha1`
Scope	Namespaced
Subresources	`/status`
Conditions	`Ready`

Example#

sources/ociregistry-auth-token.yaml
# OCIRegistry with token auth. The token is read from a Secret key and used as the
# registry login password (registries accept a token as the password). For
# username+password, use `type: basic` with `basic.username` + `basic.passwordRef`.
apiVersion: v1
kind: Secret
metadata:
  name: oci-token
  namespace: default
type: Opaque
stringData:
  token: replace_me
---
apiVersion: source.convoy.kumodo.io/v1alpha1
kind: OCIRegistry
metadata:
  name: private-oci-charts
  namespace: default
spec:
  url: oci://ghcr.io/example/charts
  auth:
    type: token
    token:
      tokenRef:
        name: oci-token
        key: token
  defaultContentType: helm
  interval: 1m0s
  minSyncInterval: 30s

Content#

An OCI registry can hold many artifact types. In convoy v0.9.0, convoy pulls only Helm chart artifacts. An artifact without a chart layer fails with no chart layer. To render kustomize or plain manifests, use a GitRepository.

spec.defaultContentType is required, and accepts helm, manifests and kustomize. Only helm content can be fetched. Pulling other OCI artifacts is planned work. Not built

The artifact version must match a tag exactly. Version ranges do not work.

Verification#

The controller sends a request to the /v2/ endpoint of the registry. A 200 or a 401 answer gives Ready=True. This check does not prove that the credentials work. A wrong credential shows only when a Release pulls a chart.

Auth types#

`auth.type`	Implemented	Fields
`none`	Yes
`basic`	Yes	`basic.username` and `basic.passwordRef`
`token`	Yes	`token.tokenRef`. convoy logs in with the username `convoy` and the token as the password.
`dockerConfig`, `oidc`, `cloudIdentity`	No	`Ready=False`, reason `Unsupported`.

TLS#

Only tls.insecureSkipVerify works. tls.caPublicCertRef is accepted, but not used.

Fields#

Field	Type	Description
`spec`	`OCIRegistrySpec`	OCIRegistrySpec defines the desired state of OCIRegistry
`spec.auth` required	`OCIRegistryAuthSpec`	Auth is the authentication method used to access the OCI registry.
`spec.auth.basic`	`BasicAuthSpec`	Basic is the basic authentication used to access the OCI registry.
`spec.auth.basic.passwordRef` required	`SecretKeySelector`	PasswordRef is the name and the key of the Secret containing the password.
`spec.auth.basic.username` required	`string`	Username is the username used for authentication.
`spec.auth.cloudIdentity`	`CloudIdentitySpec`	CloudIdentity is the cloud identity configuration used to access the OCI registry.
`spec.auth.cloudIdentity.provider` required	`string`	Provider is the cloud provider. `aws` is the cloud provider AWS. `azure` is the cloud provider Azure. `gcp` is the cloud provider GCP.
`spec.auth.dockerConfig`	`DockerConfigAuthSpec`	DockerConfig is the Docker config used to access the OCI registry.
`spec.auth.dockerConfig.secretRef` required	`SecretKeySelector`	SecretKeySelector selects a key of a Secret.
`spec.auth.oidc`	`OIDAuthSpec`	OIDC is the OIDC configuration used to access the OCI registry.
`spec.auth.oidc.audience`	`string`	Audience is the OIDC audience.
`spec.auth.oidc.clientAuth` required	`OIDCClientAuthSpec`	ClientAuth is the OIDC authentication method used for authentication.
`spec.auth.oidc.clientAuth.clientSecret`	`OIDCAuthClientSecretSpec`	ClientSecret is the reference to the Secret and the key of the Secret containing the OIDC client secret.
`spec.auth.oidc.clientAuth.clientSecret.clientSecretRef` required	`SecretKeySelector`	ClientSecretRef is the name and the key of the Secret containing the OIDC client secret.
`spec.auth.oidc.clientAuth.privateKeyJWT`	`OIDCAuthPrivateKeyJWTSpec`	PrivateKeyJWT is the reference to the Secret and the key of the Secret containing the OIDC private key JWT.
`spec.auth.oidc.clientAuth.privateKeyJWT.privateKeyRef` required	`SecretKeySelector`	PrivateKeyRef is the name and the key of the Secret containing the OIDC private key JWT.
`spec.auth.oidc.clientAuth.tlsClientAuth`	`OIDCAuthTLSClientAuthSpec`	TLSClientAuth is the reference to the Secrets and the keys of the Secret(s) containing the OIDC client certificate and key.
`spec.auth.oidc.clientAuth.tlsClientAuth.certRef` required	`SecretKeySelector`	CertRef is the name and the key of the Secret containing the OIDC client certificate.
`spec.auth.oidc.clientAuth.tlsClientAuth.keyRef` required	`SecretKeySelector`	KeyRef is the name and the key of the Secret containing the OIDC client certificate key.
`spec.auth.oidc.clientAuth.type` required	`string`	Type is the OIDC authentication method type used for authentication. `clientSecret` is the OIDC authentication method using a client secret. `privateKeyJWT` is the OIDC authentication method using a private key JWT. `tlsClientAuth` is the OIDC authentication method using TLS client authentication.
`spec.auth.oidc.clientID` required	`string`	ClientID is the OIDC client ID.
`spec.auth.oidc.issuerURL` required	`string`	IssuerURL is the URL of the OIDC issuer.
`spec.auth.oidc.scopes`	`[]string`list type: atomic	Scopes are the OIDC scopes.
`spec.auth.oidc.tls`	`TLSSpec`	TLS is the issuer TLS configuration.
`spec.auth.oidc.tls.caPublicCertRef` required	`ConfigMapKeySelector`	CAPublicCertRef is the name and the key of the ConfigMap containing the CA public certificate. The CA certificate is used to verify the IdP server's certificate.
`spec.auth.oidc.tls.insecureSkipVerify` required	`boolean`	InsecureSkipVerify is a flag to skip the certificate verification.
`spec.auth.token`	`TokenAuthSpec`	Token is the token used to access the OCI registry.
`spec.auth.token.tokenRef` required	`SecretKeySelector`	TokenRef is the name and the key of the Secret containing the token.
`spec.auth.type` required	`string`	Type is the authentication method used to access the OCI registry. `basic` is the authentication method using basic authentication. `cloudIdentity` is the authentication method using a cloud identity. `dockerConfig` is the authentication method using a Docker config. `none` is the authentication method using no authentication. `oidc` is the authentication method using OIDC. `token` is the authentication method using a token.
`spec.defaultContentType` required	`string`	DefaultContentType is the default content type used to fetch content from the OCI registry. `helm` is the content type used to fetch Helm charts. `kustomize` is the content type used to fetch kustomize bundles. `manifests` is the content type used to fetch tarballs of raw manifests.
`spec.interval` required accepted, not used	`Duration`	Interval is the poll interval for ref resolution and content fetching.
`spec.minSyncInterval` required accepted, not used	`Duration`	MinSyncInterval is the minimum interval between syncs. Used to rate limit syncs.
`spec.tls`	`TLSSpec`	TLS is the TLS configuration used to verify the OCI registry.
`spec.tls.caPublicCertRef` required accepted, not used	`ConfigMapKeySelector`	CAPublicCertRef is the name and the key of the ConfigMap containing the CA public certificate. The CA certificate is used to verify the IdP server's certificate.
`spec.tls.insecureSkipVerify` required	`boolean`	InsecureSkipVerify is a flag to skip the certificate verification.
`spec.url` required	`string`	URL is the URL of the OCI registry.

Field	Type	Description
`status`	`OCIRegistryStatus`	OCIRegistryStatus reflects the observed state of OCIRegistry
`status.conditions`	`[]Condition`list type: map, keys: type	Conditions is the list of conditions related to the OCIRegistry.
`status.lastSuccessfulProbeAt`	`Time`	LastSuccessfulProbeAt is the last time source was successfully probe.
`status.observedGeneration`	`integer`	ObservedGeneration is the last generation that was observed by the controller.
`status.releaseCount`	`integer`	ReleaseCount is the number of Release referencing the OCIRegistry.
`status.webhooks`	`[]WebhookStatus`list type: map, keys: name	Webhooks is the list of statuses of webhooks that are configured for the OCIRegistry.
`status.webhooks[].filteredCount`	`integer`	FilteredCount is the number of times the webhook was filtered.
`status.webhooks[].lastReceived`	`Time`	LastReceived is the last time the webhook was received.
`status.webhooks[].lastRejection`	`LastRejectionStatus`	LastRejection is the last time, reason and message the webhook was rejected.
`status.webhooks[].lastRejection.message`	`string`	Message is the message of the webhook rejection.
`status.webhooks[].lastRejection.reason`	`string`	Reason is the reason the webhook was rejected.
`status.webhooks[].lastRejection.rejectedAt`	`Time`	RejectedAt is the time the webhook was rejected.
`status.webhooks[].lastTriggered`	`Time`	LastTriggered is the last time the webhook was triggered.
`status.webhooks[].name` required	`string`	Name is the name of the webhook.
`status.webhooks[].receivedCount`	`integer`	ReceivedCount is the number of times the webhook was received.
`status.webhooks[].rejectedCount`	`integer`	RejectedCount is the number of times the webhook was rejected.
`status.webhooks[].triggersCount`	`integer`	TriggersCount is the number of times the webhook was triggered.
`status.webhooks[].url` required	`string`	URL is the URL of the webhook.

Conditions#

Ready · written by convoy-controller-manager

Reason	Status	Meaning
`Verified`	True	The `/v2/` endpoint of the registry answered with `200` or `401`. This check does not prove that the credentials work. A wrong credential shows only when a Release pulls a chart.
`Unsupported`	False	The auth type is not implemented. convoy does not retry with backoff. The periodic resync checks the source again.
`VerifyFailed`	False	convoy could not reach the registry. convoy retries.