Skip to content

Latest commit

 

History

History
166 lines (130 loc) · 6.06 KB

adr-001-autopilot-oci-basic-auth-support.md

File metadata and controls

166 lines (130 loc) · 6.06 KB
Raw

ADR 1: Add Support for OCI Registry and HTTP Authentication

Context

Registries are increasingly being used as generic artifact stores, expanding beyond their traditional role of hosting container images. To align with this trend, it is beneficial for Autopilot to support pulling artifacts directly from registries. Currently, Autopilot's capabilities are limited to downloading artifacts via the HTTP[S] protocols.

Enhancing Autopilot to pull artifacts directly from registries will streamline workflows and improve efficiency by allowing integration and deployment of diverse artifacts without relying solely on HTTP[S] endpoints. This update will enable Autopilot to handle registry-specific protocols and authentication mechanisms, aligning it with modern deployment practices.

Currently, Autopilot does not support the retrieval of artifacts via the HTTP protocol when authentication is required. Implementing this feature to accommodate such authentication methods would be a valuable enhancement.

Decision

Implement support in Autopilot for pulling artifacts, such as k0s binaries and image bundles, directly from a registry using the ORAS client. Additionally, add support for HTTP authentication to ensure secure access to artifacts.

Solution

Starting with the current PlanResourceURL struct:

type PlanResourceURL struct {
        // URL is the URL of a downloadable resource.
        URL string `json:"url"`

        // Sha256 provides an optional SHA256 hash of the URL's content for
        // verification.
        Sha256 string `json:"sha256,omitempty"`
}

We must specify to Autopilot where to access credentials for remote artifact pulls. This will be achieved by adjusting the struct as follows:

type PlanResourceURL struct {
        // URL is the URL of a downloadable resource.
        URL string `json:"url"`

        // Sha256 provides an optional SHA256 hash of the URL's content for
        // verification.
        Sha256 string `json:"sha256,omitempty"`

        // SecretRef holds a reference to a secret where the credentials are
        // stored. We use these credentials when pulling the artifacts from the
        // provided URL using
        // any of the supported protocols (http, https, and oci).
        SecretRef *corev1.SecretReference `json:"secretRef,omitempty"`

        // InsecureSkipTLSVerify indicates whether certificates in the remote
        // URL (if using TLS) can be ignored.
        InsecureSkipTLSVerify bool  `json:"insecureSkipTLSVerify,omitempty"`
}

SecretRef property is of type SecretReference as defined by k8s.io/api/core/v1 package. The secret pointed by the provided SecretRef will be used for pulling artifacts using either HTTP[S] or OCI protocols and is expected to by of type kubernetes.io/dockerconfigjson if the protocol in use is oci:// or of type Opaque if protocols http:// or https:// are used (see below for details on the Secret layout).

Example configuration for OCI:

url: oci://my.registry/binaries/k0s:v1.30.1+k0s.0
sha256: e95603f167cce6e3cffef5594ef06785b3c1c00d3e27d8e4fc33824fe6c38a99
secretRef:
  namespace: kube-system
  name: artifacts-registry

Example configuration for HTTPS:

url: https://my.file.server/binaries/k0s-v1.30.1+k0s.0
sha256: e95603f167cce6e3cffef5594ef06785b3c1c00d3e27d8e4fc33824fe6c38a99
secretRef:
  namespace: kube-system
  name: artifacts-basic-auth

Example configuration for HTTP:

url: http://my.file.server/binaries/k0s-v1.30.1+k0s.0
sha256: e95603f167cce6e3cffef5594ef06785b3c1c00d3e27d8e4fc33824fe6c38a99
secretRef:
  namespace: kube-system
  name: artifacts-token-based-auth

Secrets Layout

For secrets of type kubernetes.io/dockerconfigjson the format is the default for Docker authentications, equal to what is used in a Pod's pull secret. For further details you can refer to the official documentation.

When it comes to the Opaque secret layout (used for HTTP requests) Autopilot will accept the following entries:

  • username and password: if both are set then Autopilot will attempt to pull the artifacts using Basic Authentication.
  • authorization: if this property is set then the Authorization header will be set to its value when pulling the artifacts.

No other property will be parsed and used. For sake of defining the expected behaviour in case of conflicting configurations:

In the case where the three properties are set (username, password, and authorization) Autopilot will ignore username and password, i.e. authorization takes precedence over username and password.

The authorization entry is used as is, its content is placed directly into the Authorization header. For example a secret like the following will make Autopilot to set the Authorization header to Bearer abc123def456ghi789jkl0:

apiVersion: v1
kind: Secret
metadata:
  name: creds
  namespace: kube-system
data:
  authorization: "Bearer abc123def456ghi789jkl0"

Additional Details

  • The InsecureSkipTLSVerify property is equivalent of defining InsecureSkipTLSVerify on a Go HTTP client.
  • The InsecureSkipTLSVerify property will be valid for both oci:// and https:// protocols.
  • If a protocol is not specified or an incorrect one is provided, an error state should be activated.
  • If no SecretRef is defined, access will be anonymous (no authentication).

Status

Proposed

Consequences

  • Users will have an additional protocol to be aware of.
  • If the Secret referenced by SecretRef does not exist, the download will fail.
  • Users need to be notified about different failure types (e.g., unreadable secret, invalid secret).
  • Additional configuration is required to handle authentication, ensuring secure access to resources.
  • We will allow downloads from remote places using self-signed certificates if requested to.