|
| 1 | +--- |
| 2 | +aliases: [/imgpkg/docs/latest/air-gapped-workflow] |
| 3 | +title: Air-gapped Workflow |
| 4 | +--- |
| 5 | + |
| 6 | +## Scenario |
| 7 | + |
| 8 | +You want to ensure Kubernetes application does not rely on images from external registries when deployed. |
| 9 | + |
| 10 | +This scenario _also_ applies when trying to ensure that all images are consolidated into a single registry, even if that registry is not air-gapped. |
| 11 | + |
| 12 | +## Prerequisites |
| 13 | + |
| 14 | +To complete this workflow you will need access to an OCI registry like Docker Hub, and optionally, |
| 15 | +a Kubernetes cluster. (If you would like to use a local registry and Kubernetes cluster, try using [Kind](https://kind.sigs.k8s.io/docs/user/local-registry/)) |
| 16 | + |
| 17 | +If you would like to deploy the results of this scenario to your Kubernetes cluster, you will additionally need [`kbld`](/kbld) and kubectl. |
| 18 | + |
| 19 | +If any of your bundles contain [non-distributable layers](commands.md#non-distributable-or-foreign-layers) you will need to include |
| 20 | +the `--include-non-distributable-layers` flag to each copy command in the examples provided. |
| 21 | + |
| 22 | +--- |
| 23 | +## Step 1: Finding bundle in source registry |
| 24 | + |
| 25 | +If you have already pushed a bundle to the registry, continue to the next step. |
| 26 | + |
| 27 | +If you are trying to bundle your own or third-part software, you will need to create a bundle. Refer to basic workflow's ["Step 1: Creating the bundle" and "Step 2: Pushing the bundle to registry"](basic-workflow.md#step-1-creating-the-bundle). |
| 28 | + |
| 29 | +--- |
| 30 | +## Step 2: Two methods of copying bundles |
| 31 | + |
| 32 | +You have two options how to transfer bundle from one registry to another: |
| 33 | + |
| 34 | +- Option 1: From a common location connected to both registries. This option is more efficient because only changed image layers will be transfered between registries. |
| 35 | +- Option 2: With intermediate tarball. This option works best when registries have no common network access. |
| 36 | + |
| 37 | +### Option 1: From a location connected to both registries |
| 38 | + |
| 39 | +1. Get to a location that can access both registries |
| 40 | + |
| 41 | + This may be a server that has access to both internal and external networks. If there is no such location, you will have to use "Option 2" below. |
| 42 | + |
| 43 | +1. [Authenticate](auth.md) with both source, and destination registries |
| 44 | + |
| 45 | +1. Run following command to copy bundle from one registry to another: |
| 46 | + |
| 47 | + ```bash-plain |
| 48 | + $ imgpkg copy -b index.docker.io/user1/simple-app-bundle:v1.0.0 --to-repo registry.corp.com/apps/simple-app-bundle |
| 49 | +
|
| 50 | + copy | exporting 2 images... |
| 51 | + copy | will export index.docker.io/user1/simple-app-bundle@sha256:4c8b96d4fffdfae29258d94a22ae4ad1fe36139d47288b8960d9958d1e63a9d0 |
| 52 | + copy | will export index.docker.io/user1/simple-app-bundle@sha256:70225df0a05137ac385c95eb69f89ded3e7ef3a0c34db43d7274fd9eba3705bb |
| 53 | + copy | exported 2 images |
| 54 | + copy | importing 2 images... |
| 55 | + copy | importing index.docker.io/user1/simple-app-bundle@sha256:70225df0a05137ac385c95eb69f89ded3e7ef3a0c34db43d7274fd9eba3705bb |
| 56 | + -> registry.corp.com/apps/simple-app-bundle@sha256:70225df0a05137ac385c95eb69f89ded3e7ef3a0c34db43d7274fd9eba3705bb... |
| 57 | + copy | importing index.docker.io/user1/simple-app-bundle@sha256:4c8b96d4fffdfae29258d94a22ae4ad1fe36139d47288b8960d9958d1e63a9d0 |
| 58 | + -> registry.corp.com/apps/simple-app-bundle@sha256:4c8b96d4fffdfae29258d94a22ae4ad1fe36139d47288b8960d9958d1e63a9d0... |
| 59 | + copy | imported 2 images |
| 60 | + Succeeded |
| 61 | + ``` |
| 62 | +
|
| 63 | + The bundle, and all images referenced in the bundle, are copied to the destination registry. |
| 64 | +
|
| 65 | + Flags used in the command: |
| 66 | + * `-b` (`--bundle`) indicates the bundle location in the source registry |
| 67 | + * `--to-repo` indicates the registry where the bundle and associated images should be copied to |
| 68 | +
|
| 69 | +### Option 2: With intermediate tarball |
| 70 | +
|
| 71 | +1. Get to a location that can access source registry |
| 72 | +
|
| 73 | +1. [Authenticate with the source registry](auth.md) |
| 74 | +
|
| 75 | +1. Save the bundle to a tarball |
| 76 | +
|
| 77 | + ```bash-plain |
| 78 | + $ imgpkg copy -b index.docker.io/user1/simple-app-bundle:v1.0.0 --to-tar /tmp/my-image.tar |
| 79 | +
|
| 80 | + copy | exporting 2 images... |
| 81 | + copy | will export index.docker.io/user1/simple-app-bundle@sha256:4c8b96d4fffdfae29258d94a22ae4ad1fe36139d47288b8960d9958d1e63a9d0 |
| 82 | + copy | will export index.docker.io/user1/simple-app-bundle@sha256:70225df0a05137ac385c95eb69f89ded3e7ef3a0c34db43d7274fd9eba3705bb |
| 83 | + copy | exported 2 images |
| 84 | + copy | writing layers... |
| 85 | + copy | done: file 'manifest.json' (13.71µs) |
| 86 | + copy | done: file 'sha256-233f1d0dbdc8cf675af965df8639b0dfd4ef7542dfc9fcfd03bfc45c570b0e4d.tar.gz' (47.616µs) |
| 87 | + copy | done: file 'sha256-8ece9ac45f2b7228b2ed95e9f407b4f0dc2ac74f93c62ff1156f24c53042ba54.tar.gz' (43.204905ms) |
| 88 | + Succeeded |
| 89 | + ``` |
| 90 | +
|
| 91 | + Flags used in the command: |
| 92 | + * `-b` (`--bundle`) indicates the bundle location in the source registry |
| 93 | + * `--to-tar` indicates the local location to write a tar file containing the bundle assets |
| 94 | +
|
| 95 | +1. Transfer the local tarball `/tmp/my-image.tar` to a location with access to the destination registry |
| 96 | +
|
| 97 | +1. [Authenticate with the destination registry](auth.md) |
| 98 | +
|
| 99 | +1. Import the bundle from your tarball to the destination registry: |
| 100 | +
|
| 101 | + ```bash-plain |
| 102 | + $ imgpkg copy --tar /tmp/my-image.tar --to-repo registry.corp.com/apps/simple-app-bundle |
| 103 | +
|
| 104 | + copy | importing 2 images... |
| 105 | + copy | importing index.docker.io/user1/simple-app-bundle@sha256:70225df0a05137ac385c95eb69f89ded3e7ef3a0c34db43d7274fd9eba3705bb -> registry.corp.com/apps/simple-app-bundle@sha256:70225df0a05137ac385c95eb69f89ded3e7ef3a0c34db43d7274fd9eba3705bb... |
| 106 | + copy | importing index.docker.io/user1/simple-app-bundle@sha256:4c8b96d4fffdfae29258d94a22ae4ad1fe36139d47288b8960d9958d1e63a9d0 -> registry.corp.com/apps/simple-app-bundle@sha256:4c8b96d4fffdfae29258d94a22ae4ad1fe36139d47288b8960d9958d1e63a9d0... |
| 107 | + copy | imported 2 images |
| 108 | + Succeeded |
| 109 | + ``` |
| 110 | +
|
| 111 | + The bundle, and all images referenced in the bundle, are copied to the destination registry. |
| 112 | +
|
| 113 | + Flags used in the command: |
| 114 | + * `--tar` indicates the path to a tar file containing the assets to be copied to a registry |
| 115 | + * `--to-repo` indicates destination bundle location in the registry |
| 116 | +
|
| 117 | +--- |
| 118 | +## Step 3: Pulling bundle from destination registry |
| 119 | +
|
| 120 | +1. [Authenticate with the destination registry](auth.md) |
| 121 | +
|
| 122 | +1. Pull the bundle from the destination registry: |
| 123 | +
|
| 124 | + ```bash-plain |
| 125 | + $ imgpkg pull -b registry.corp.com/apps/simple-app-bundle:v1.0.0 -o /tmp/bundle |
| 126 | +
|
| 127 | + Pulling image 'registry.corp.com/apps/simple-app-bundle@sha256:70225df0a05137ac385c95eb69f89ded3e7ef3a0c34db43d7274fd9eba3705bb' |
| 128 | + Extracting layer 'sha256:233f1d0dbdc8cf675af965df8639b0dfd4ef7542dfc9fcfd03bfc45c570b0e4d' (1/1) |
| 129 | + Locating image lock file images... |
| 130 | + All images found in bundle repo; updating lock file: /tmp/bundle/.imgpkg/images.yml |
| 131 | +
|
| 132 | + Succeeded |
| 133 | + ``` |
| 134 | +
|
| 135 | + Flags used in the command: |
| 136 | + * `-b` (`--bundle`) indicates to pull a particular bundle from a registry |
| 137 | + * `-o` (`--output`) indicates the local folder where the bundle will be unpacked |
| 138 | +
|
| 139 | + Note that the `.imgpkg/images.yml` file was updated with the destination registry locations of the images. This happened because, in the prior step, the images referenced by the bundle were copied into the destination registry. |
| 140 | +
|
| 141 | + ```bash-plain |
| 142 | + $ cat /tmp/bundle/.imgpkg/images.yml |
| 143 | + apiVersion: imgpkg.carvel.dev/v1alpha1 |
| 144 | + kind: ImagesLock |
| 145 | + images: |
| 146 | + - image: registry.corp.com/apps/simple-app-bundle@sha256:4c8b96d4fffdfae29258d94a22ae4ad1fe36139d47288b8960d9958d1e63a9d0 |
| 147 | + annotations: |
| 148 | + kbld.carvel.dev/id: docker.io/dkalinin/k8s-simple-app |
| 149 | + ``` |
| 150 | +
|
| 151 | +--- |
| 152 | +## Step 4: Use pulled bundle contents |
| 153 | +
|
| 154 | +Regardless which location the bundle is downloaded from, source registry or destination registry, use of the pulled bundle contents remains the same. Continue with ["Step 4: Use pulled bundle contents"](basic-workflow.md#step-4-use-pulled-bundle-contents) in the basic workflow. |
0 commit comments