github.com/argoproj/argo-cd/v3@v3.2.1/docs/user-guide/oci.md (about)

     1  # OCI
     2  
     3  ## Declarative
     4  
     5  Argo CD supports using OCI (Open Container Initiative) images as an application source. 
     6  You can install applications using OCI images through the UI, or in the declarative GitOps way.  
     7  Here is an example:
     8  
     9  ```yaml
    10  apiVersion: argoproj.io/v1alpha1
    11  kind: Application
    12  metadata:
    13    name: my-custom-image
    14    namespace: argocd
    15  spec:
    16    project: default
    17    source:
    18      path: .
    19      repoURL: oci://registry-1.docker.io/some-user/my-custom-image
    20      targetRevision: 1.16.1
    21    destination:
    22      server: "https://kubernetes.default.svc"
    23      namespace: my-namespace
    24  ```
    25  
    26  Another example using a public OCI helm chart:
    27  
    28  ```yaml
    29  apiVersion: argoproj.io/v1alpha1
    30  kind: Application
    31  metadata:
    32    name: nginx
    33  spec:
    34    project: default
    35    source:
    36      path: .
    37      repoURL: oci://registry-1.docker.io/bitnamicharts/nginx 
    38      targetRevision: 15.9.0
    39      helm:
    40        valuesObject:
    41          some-value: foo
    42    destination:
    43      name: "in-cluster"
    44      namespace: nginx
    45  ```
    46  
    47  The key to start using OCI images are the following components in the application spec:  
    48  
    49  * `repoURL`: Specify the OCI image repository URL using the `oci://` scheme, followed by the registry and image name.
    50  * `targetRevision`: Use this field to specify the desired image tag or digest.
    51  * `path`: Use this field to select a relative path from the expanded image. If you don't want to select a subpath, use `.`.
    52  In the case of OCI Helm charts (an OCI artifact where the `mediaType` is set to `application/vnd.cncf.helm.chart.content.v1.tar+gzip`), 
    53  the path should always be set to `.`. 
    54  
    55  ## Usage Guidelines
    56  
    57  First off, you'll need to have a repository that is OCI-compliant. As an example, DockerHub, ECR, GHCR and GCR all fit 
    58  the bill.
    59  
    60  Secondly, Argo CD expects an OCI image to contain a single layer. It also expects an OCI image to have a media type which 
    61  is accepted by the Argo CD repository server. By default, Argo CD accepts one of the following media types for the image 
    62  layer:
    63  
    64  * `application/vnd.oci.image.layer.v1.tar+gzip`
    65  * `application/vnd.cncf.helm.chart.content.v1.tar+gzip`
    66  
    67  Custom media types can be configured by setting the `ARGOCD_REPO_SERVER_OCI_LAYER_MEDIA_TYPES` environment variable 
    68  in the repo-server deployment.
    69  
    70  To create an OCI artifact compatible with Argo CD, there are a multitude of tools to choose from. For this example we'll
    71  use [ORAS](https://oras.land/). Navigate to the directory where your manifests are located and run `oras push`.
    72  
    73  ```shell
    74  oras push <registry-url>/guestbook:latest .
    75  ```
    76  
    77  ORAS will take care of packaging the directory to a single layer and setting the `mediaType` to 
    78  `application/vnd.oci.image.layer.v1.tar+gzip`.
    79  
    80  You can also package your OCI image using a compressed archive.
    81  
    82  ```shell
    83  # Create a tarball of the directory containing your manifests. If you are not in the current directory, please ensure 
    84  # that you are setting the correct parent of the directory (that is what the `-C` flag does).
    85  tar -czvf archive.tar.gz -C manifests .
    86  ```
    87  
    88  Then, you can push the archive to your OCI registry using ORAS:
    89  
    90  ```shell
    91  # In the case of tarballs, you currently need to set the media type manually. 
    92  oras push <registry-url>/guestbook:latest archive.tar.gz:application/vnd.oci.image.layer.v1.tar+gzip
    93  ```
    94  
    95  ## OCI Metadata Annotations
    96  
    97  Argo CD can display standard OCI metadata annotations, providing additional context and information about your OCI 
    98  images directly in the Argo CD UI.
    99  
   100  ### Supported Annotations
   101  
   102  Argo CD recognizes and displays the following standard OCI annotations:
   103  
   104  * `org.opencontainers.image.title`
   105  * `org.opencontainers.image.description`
   106  * `org.opencontainers.image.version`
   107  * `org.opencontainers.image.revision`
   108  * `org.opencontainers.image.url`
   109  * `org.opencontainers.image.source`
   110  * `org.opencontainers.image.authors`
   111  * `org.opencontainers.image.created`
   112  
   113  Using the previous example with ORAS, we can set annotations which Argo CD can make use of:
   114  
   115  ```shell
   116  oras push -a "org.opencontainers.image.authors=some author" \
   117            -a "org.opencontainers.image.url=http://some-url" \
   118            -a "org.opencontainers.image.version=some-version" \
   119            -a "org.opencontainers.image.source=http://some-source" \
   120            -a "org.opencontainers.image.description=some description" \
   121            <registry-url>/guestbook:latest .
   122  ```