k8s.io/registry.k8s.io@v0.3.1/docs/mirroring/README.md (about)

     1  # Mirroring
     2  
     3  This guide covers mirroring images you use on registry.k8s.io
     4  to a host under your own control and using those images.
     5  
     6  The specific sub-steps will depend on the tools you use, but in general you will need to:
     7  
     8  1. Identify the images you need: [Identifying Images To Mirror][identifying-images]
     9  2. Mirror those images to your own registry: [Mirroring Images][mirroring-images]
    10  3. Configure your tools to use the mirrored images: [Using Mirrored Images][using-mirrored-images]
    11  
    12  We have guides here for each of these steps.
    13  
    14  ## Identifying Images To Mirror
    15  <!--
    16  NOTE: Wherever possible do not duplicate external content.
    17  
    18  Instead, link to existing official guides and merely provide a lightweight pointer here.
    19  
    20  See: https://kubernetes.io/docs/contribute/style/content-guide/#dual-sourced-content
    21  -->
    22  
    23  <!--TODO: Generically identifying registry.k8s.io images in manifests / charts / addons.-->
    24  
    25  If you have a running cluster then our [community-images] krew plugin can
    26  help you identify Kubernetes Project image references to mirror like this:
    27  
    28  ```console
    29  kubectl community-images --mirror
    30  ```
    31  
    32  **NOTE**: This will only find images specified in your currently running pods,
    33  and not for example the "pause" image used to implement pods in containerd / cri-o / dockershim.
    34  
    35  For specific tools we have these guides:
    36  
    37  - For containerd see: [containerd.md](./containerd.md)
    38  - For cri-o see: [cri-o.md](./cri-o.md)
    39  - For cri-dockerd see: [cri-dockerd.md](./cri-dockerd.md)
    40  - For kubeadm see: [kubeadm.md](./kubeadm.md)
    41  - For kOps see: [kOps.md](./kOps.md)
    42  - For Cluster API see: [cluster-api.md](./cluster-api.md)
    43  
    44  
    45  ## Mirroring Images
    46  <!--
    47  NOTE: Wherever possible do not duplicate external content.
    48  
    49  Instead, link to existing official guides and merely provide a lightweight pointer here.
    50  
    51  See: https://kubernetes.io/docs/contribute/style/content-guide/#dual-sourced-content
    52  -->
    53  
    54  Here are some options for copying images you wish to mirror to your own registry.
    55  
    56  <!-- FOSS Mirroring Tools Go First Below Here! -->
    57  <!-- Commercial / Non-FOSS Mirroring Options Go Further Below -->
    58  
    59  ### Mirroring With `crane` Or `gcrane`
    60  
    61  `crane` is an open-source tool for interacting with remote images and registries.
    62  `gcrane` is a superset of crane with GCP specific additional features.
    63  
    64  For `crane` use `crane copy registry.k8s.io/pause:3.9 my-registry.com/pause:3.9`.
    65  Docs: https://github.com/google/go-containerregistry/blob/main/cmd/crane/doc/crane_copy.md
    66  
    67  For `gcrane` see: https://cloud.google.com/container-registry/docs/migrate-external-containers
    68  
    69  To mirror all images surfaced by [community-images], you can use this shell snippet:
    70  ```shell
    71  # set MIRROR to your own host
    72  export MIRROR=my-registry.com
    73  # copy all Kubernetes project images in your current cluster to MIRROR
    74  kubectl community-images --mirror --plain |\
    75     xargs -i bash -c 'set -x; crane copy "$1" "${1/registry.k8s.io/'"${MIRROR}"'}"' - '{}'
    76  ```
    77  
    78  Once you're done, see [Using Mirrored Images][using-mirrored-images].
    79  
    80  ### Mirroring With `oras`
    81  
    82  `oras` is an open-source tool for managing images and other artifacts in OCI registries.
    83  
    84  For `oras` use `oras copy registry.k8s.io/pause:3.9 my-registry.com/pause:3.9`.
    85  Docs: https://oras.land/cli_reference/4_oras_copy/
    86  
    87  To mirror all images surfaced by [community-images], you can use this shell snippet:
    88  ```shell
    89  # set MIRROR to your own host
    90  export MIRROR=my-registry.com
    91  # copy all Kubernetes project images in your current cluster to MIRROR
    92  kubectl community-images --mirror --plain |\
    93     xargs -i bash -c 'set -x; oras copy "$1" "${1/registry.k8s.io/'"${MIRROR}"'}"' - '{}'
    94  ```
    95  
    96  Once you're done, see [Using Mirrored Images][using-mirrored-images].
    97  
    98  ### Mirroring With Harbor
    99  
   100  You can use Harbor to set up a proxy cache for Kubernetes images.
   101  
   102  From the Harbor web interface, go to "Registries" and click "New Endpoint".
   103  Create an endpoint `registry.k8s.io` with the endpoint URL https://registry.k8s.io.
   104  Go to "Projects" and click "New Project".
   105  Create a project named something like 'k8s', click "Proxy Cache" and select your `registry.k8s.io` endpoint.
   106  Docs: https://goharbor.io/docs/2.1.0/administration/configure-proxy-cache/
   107  
   108  Once you're done, see [Using Mirrored Images][using-mirrored-images].
   109  
   110  <!-- NON-FOSS Mirroring Tools Go Below Here! -->
   111  
   112  ### Mirroring With ECR
   113  
   114  AWS ECR wrote a guide for configuring a `registry.k8s.io` pull-through cache here:
   115  
   116  https://aws.amazon.com/blogs/containers/announcing-pull-through-cache-for-registry-k8s-io-in-amazon-elastic-container-registry/
   117  
   118  After following this guide, you may additionally want to see our [Using Mirrored Images][using-mirrored-images] reference below.
   119  
   120  
   121  ## Using Mirrored Images
   122  <!--
   123  NOTE: Wherever possible do not duplicate external content.
   124  
   125  Instead, link to existing official guides and merely provide a lightweight pointer here.
   126  
   127  See: https://kubernetes.io/docs/contribute/style/content-guide/#dual-sourced-content
   128  -->
   129  
   130  In many cases it is sufficient to update the `image` fields in your
   131  Kubernetes manifests (deployments, pods, replicasets, etc) to reference
   132  your mirrored images instead.
   133  
   134  For specific tools we have these guides:
   135  
   136  - For containerd see: [containerd.md](./containerd.md)
   137  - For cri-o see: [cri-o.md](./cri-o.md)
   138  - For cri-dockerd see: [cri-dockerd.md](./cri-dockerd.md)
   139  - For kubeadm see: [kubeadm.md](./kubeadm.md)
   140  - For kOps see: [kOps.md](./kOps.md)
   141  - For Cluster API see: [cluster-api.md](./cluster-api.md)
   142  
   143  [identifying-images]: #Identifying-Images-To-Mirror
   144  [mirroring-images]: #Mirroring-Images
   145  [using-mirrored-images]: #Using-Mirrored-Images
   146  [community-images]: https://github.com/kubernetes-sigs/community-images
   147