github.com/argoproj/argo-cd/v2@v2.10.5/docs/proposals/native-oci-support.md (about)

     1  ---
     2  title: Argo CD first-class OCI support
     3  authors:
     4    - "@sabre1041"
     5    - "@crenshaw-dev"
     6    - "@todaywasawesome"
     7    
     8  sponsors:
     9    - TBD
    10  reviewers:
    11    - "@alexmt"
    12  approvers:
    13    - "@alexmt"
    14  
    15  creation-date: 2023-05-09
    16  ---
    17  
    18  # Argo CD first-class OCI support
    19  
    20  Storing and retrieving manifests within in OCI registries
    21  
    22  ## Summary
    23  
    24  Currently, Argo CD supports obtaining manifests from either a Git repository, a Helm chart repository, or a Helm chart stored within an OCI registry. Given that OCI registries are more frequently being used to store content aside from container images, introduce a mechanism for storing and retrieving manifests that can be used by any of the existing supported tools in any of the supported methods of representing assets that are to be applied to a Kubernetes environment.
    25  
    26  
    27  ## Motivation
    28  
    29  The industry is seeing a rapid adoption of OCI Artifacts as a method for storing and retrieving content. Adding support for sourcing resources stored in OCI artifacts not only provides immediate benefits, but opens up additional possible integrations in the future.
    30  
    31  **Dependency Reduction**
    32  
    33   At the present time, a user must have access to either a Git repository, or a remote Helm chart repository. Most users or enterprise organizations already have access to an OCI registry as it represents the primary source of image related content within a Kubernetes environment. By sourcing assets from OCI registries, no additional infrastructure is required in order to store a variety of content types simplifying the set of requirements in order to begin to fully leverage the capabilities of Argo CD.
    34  
    35  **Market Relevance**
    36  
    37  Argo CD continues to be one of the most popular GitOps tools in the industry. As the industry continues to evolve, other tools within the GitOps market have already began to adopt OCI artifacts as a source for storing and retrieving GitOps resources.
    38  
    39  ### Goals
    40  
    41  * Enable the retrieval of resources stored as artifacts in OCI registries that are formatted in any of the supported options (Kustomize, Jsonnet, Helm, plain-manifest, CMPs, etc)
    42  * Define a format for storing resources that can be processed by Argo CD as an OCI artifact including the composition and [Media Type(s)](https://github.com/opencontainers/image-spec/blob/main/media-types.md)
    43  * Support the retrieval of artifacts from OCI registries using custom / self signed TLS certificates.
    44  * Support the retrieval of artifacts from OCI registries requiring authentication. 
    45  
    46  ### Non-Goals
    47  
    48  * CLI Integration to package and publish resources in a format for storage in an OCI registry
    49  * Attach metadata to OCI artifact manifest to provide additional details related to the content (such as original Git source [URL, revision])
    50  
    51  ## Proposal
    52  
    53  This is where we get down to details of what the proposal is about.
    54  
    55  ### Use cases
    56  
    57  Add a list of detailed use cases this enhancement intends to take care of.
    58  
    59  #### Publishing and retrieval of content from OCI registries:
    60  
    61  As a user, I would like to make use of content that is represented by any of the  supported options (Kustomize, Jsonnet, Helm, plain-manifest, etc) or those that could be consumed using a Config Management Plugin from an OCI registry.
    62  
    63  #### Authenticating to OCI registries:
    64  
    65  As a user, I would like to enforce proper security controls by requiring authentication to an OCI registry and configure Argo CD to be able to interact with this registry.
    66  
    67  #### CLI Integration:
    68  
    69  As a user, I would like the ability to produce, store and retrieve resources (pull/push) in a OCI registry using the Argo CD CLI.
    70  
    71  ### Implementation Details/Notes/Constraints
    72  
    73  The Argo CD repo-server currently maintains two types of clients - Helm and git. By adding a third client, and invoking it in the same places as the other two, we can support OCI artifacts.
    74  
    75  It seems likely that we should create a new, common interface to represent all three clients. Then we can instantiate the client we need, toggling on whatever value in the repo config determines what kind of repo we're fetching from.
    76  
    77  #### Format of OCI Artifact
    78  
    79  An OCI artifact can contain any type of binary content. It is important that the content be formatted in a manner that can be consumed by Argo CD.
    80  
    81  #### Content
    82  
    83  Resources that is consumed by Argo CD can be represented by a series of files and folders. To be stored within an OCI artifact, these assets are stored within a compressed tar archive (.tar.gz) OCI layer. The [OCI Image Specification](https://specs.opencontainers.org/image-spec/) allows for metadata to be added through the use of annotations to provide attribute based details describing the included content. This level of detail is important as it satisfies many of the existing capabilities of Argo CD for tracking content, such as Git repository URL, branch name/revision.
    84  
    85  
    86  #### Media Types
    87  
    88  The [OCI Image Specification](https://specs.opencontainers.org/image-spec/) makes extensive use of Media Types to identity the format of content. To provide not only a way that signifies the content of the OCI artifact contains Argo CD manifests, but to define the structure of the content. An understanding of the composition and requirements enable a broad ecosystem of tooling that can be used to produce and consume Argo CD resources within OCI registries.
    89  
    90  Two new Media Types will be used for this purpose as defined below:
    91  
    92  * `application/vnd.cncf.argoproj.argocd.content.v1.tar+gzip` - Primary asset stored within the OCI artifact containing a gzip compressed tar archive of Argo CD resources. Further details are outlined in the prior section.
    93  * `application/vnd.cncf.argoproj.argocd.config.v1+json` - An [OCI Image Configuration](https://specs.opencontainers.org/image-spec/config/)
    94  
    95  
    96  ### Detailed examples
    97  
    98  
    99  ### Security Considerations
   100  
   101  The direct integration with an external endpoint from the core subsystem of Argo CD introduces several considerations as it relates to security. It is worthy to note that Argo CD currently does support sourcing Helm charts that are stored within OCI registries. However, this interaction is performed by Helm and its underlying library, [ORAS](https://oras.land), and not Argo CD itself. Capabilities included within this proposal can make use of the same libraries to facilitate the interaction.
   102  
   103  #### Credentials
   104  
   105  Security controls may be enforced within the OCI registry to enforce that clients authenticate. The introduction of additional mechanisms to authenticate against target systems is outside the scope of this proposal. However, an integration with existing capabilities and features, such as sourcing from _repository_ credentials is required.
   106  
   107  
   108  ### Risks and Mitigation's
   109  
   110  #### Overlap with existing Helm OCI integration
   111  
   112  Argo CD already includes support for sourcing Helm Charts from OCI registries and the retrieval is delegated to functionality provided by Helm. Considerations must be taken into account to determine whether the intent by the end user is to consume an OCI artifact containing Argo CD related resources or a Helm chart. One such method for addressing this concern is to inspect the `mediaType` of the OCI artifact.
   113  
   114  
   115  ### Upgrade / Downgrade Strategy
   116  
   117  If applicable, how will the component be upgraded and downgraded? Make sure this is in the test
   118  plan.
   119  
   120  Consider the following in developing an upgrade/downgrade strategy for this enhancement:
   121  
   122  - What changes (in invocations, configurations, API use, etc.) is an existing cluster required to
   123    make on upgrade in order to keep previous behavior?
   124  - What changes (in invocations, configurations, API use, etc.) is an existing cluster required to
   125    make on upgrade in order to make use of the enhancement?
   126  
   127  ## Drawbacks
   128  
   129  * Sourcing content from an OCI registry may be perceived to be against GitOps principles as content is not sourced from a Git repository. This concern could be mitigated by attaching additional details related to the content (such as original Git source [URL, revision]). Though it should be noted that the GitOps principles only require a source of truth to be visioned and immutable which OCI registires support.
   130  
   131  ## Alternatives
   132  
   133  ### Config Management Plugin
   134  
   135  Content stored within OCI artifacts could be sourced using a Config Management Plugin which would not require changes to the core capabilities provided by Argo CD. However, this would be hacky and not represent itself within the Argo CD UI.