|
| 1 | +--- |
| 2 | +aliases: [/kapp-controller/docs/latest/air-gapped-workflow] |
| 3 | +title: Install Packages in an air-gapped (offline) environment |
| 4 | +--- |
| 5 | + |
| 6 | +The documentation below covers topics from the [imgpkg air-gapped workflow docs](/imgpkg/docs/latest/air-gapped-workflow) |
| 7 | +more concisely in order to focus on applying these workflows to kapp-controller package repositories. |
| 8 | + |
| 9 | +## Scenario |
| 10 | + |
| 11 | +You have a [PackageRepository](packaging#packagerepository-cr) in an [imgpkg bundle format](/imgpkg/docs/latest/resources/#bundle) |
| 12 | +in an external OCI registry that you would like to move into an OCI registry in an air-gapped environment. Once relocated, you would |
| 13 | +like to deploy the bundle as part of a PackageRepository to a Kubernetes cluster. |
| 14 | + |
| 15 | +## Prerequisites |
| 16 | + |
| 17 | +In order to go through this process of moving an imgpkg bundle to an air-gapped environment, you will need to have [imgpkg](/imgpkg) |
| 18 | +installed. More information on installing Carvel tools, including `imgpkg`, can be found [here](/#whole-suite). |
| 19 | + |
| 20 | +## Copy PackageRepository bundle to new location |
| 21 | + |
| 22 | +Most of the steps documented for the [imgpkg air-gapped workflow docs](/imgpkg/docs/latest/air-gapped-workflow#step-1-finding-bundle-in-source-registry) |
| 23 | +still apply in the case of working with kapp-controller package repositories. A summary of these docs is that you will need to copy your package repository |
| 24 | +bundle with `imgpkg` via one of the following options: |
| 25 | + |
| 26 | +- **Option 1:** From a common location connected to both registries. This option is more efficient because only changed image layers will be transferred between registries. |
| 27 | +- **Option 2:** With intermediate tarball. This option works best when registries have no common network access. |
| 28 | + |
| 29 | +More detailed documents for [Option 1](/imgpkg/docs/latest/air-gapped-workflow/#option-1-from-a-location-connected-to-both-registries) and |
| 30 | +[Option 2](/imgpkg/docs/latest/air-gapped-workflow/#option-2-with-intermediate-tarball) can be found at the attached links. |
| 31 | + |
| 32 | +A summary of steps for relocating a package repository bundle to an air-gapped environment are documented for both options below: |
| 33 | + |
| 34 | +For **Option 1**: |
| 35 | + |
| 36 | +1. Navigate to a location that can access both registries. If there is no such location, you have to use **Option 2** steps. |
| 37 | +1. [Authenticate](/imgpkg/docs/latest/auth.md) with both source and destination registries. |
| 38 | +1. Copy PackageRepository bundle to the new location by running: |
| 39 | + |
| 40 | + ``` |
| 41 | + imgpkg copy -b index.docker.io/user1/simple-app-bundle:v1.0.0 --to-repo final-registry.corp.com/apps/simple-app-bundle |
| 42 | + ``` |
| 43 | +
|
| 44 | +For **Option 2**: |
| 45 | +
|
| 46 | +1. Navigate to a location that can access the source registry. |
| 47 | +1. [Authenticate](/imgpkg/docs/latest/auth.md) with the source registry. |
| 48 | +1. Compress PackageRepository bundle into a tarball file by running: |
| 49 | +
|
| 50 | + ``` |
| 51 | + imgpkg copy -b index.docker.io/user1/simple-app-bundle:v1.0.0 --to-tar /tmp/my-image.tar |
| 52 | + ``` |
| 53 | +
|
| 54 | + **Note:** Make sure the tar file is in a location that has access to the destination registry. |
| 55 | +
|
| 56 | +1. [Authenticate](/imgpkg/docs/latest/auth.md) with the destination registry. |
| 57 | +
|
| 58 | +1. Copy the tarball file to the new location by running: |
| 59 | +
|
| 60 | + ``` |
| 61 | + imgpkg copy --tar /tmp/my-image.tar --to-repo final-registry.corp.com/apps/simple-app-bundle |
| 62 | + ``` |
| 63 | +
|
| 64 | +## Use Relocated Bundle or Image with PackageRepository |
| 65 | +
|
| 66 | +Once you have relocated the package repository bundle into the destination OCI registry in your air-gapped environment, you can |
| 67 | +now reference the relocated bundle in a PackageRepository definition: |
| 68 | +
|
| 69 | +```yaml |
| 70 | +--- |
| 71 | +apiVersion: install.package.carvel.dev/v1alpha1 |
| 72 | +kind: PackageRepository |
| 73 | +metadata: |
| 74 | + name: simple-package-repository |
| 75 | +spec: |
| 76 | + fetch: |
| 77 | + imgpkgBundle: |
| 78 | + image: final-registry.corp.com/apps/simple-app-bundle |
| 79 | +``` |
| 80 | + |
| 81 | +In the event your PackageRepository needs authentication to pull the bundle, you can read more about kapp-controller's |
| 82 | +[private authentication workflows using secretgen-controller](private-registry-auth.md) or [without secretgen-controller](private-registry-auth.md#packagerepository-authentication-without-secretgen-controller). |
| 83 | + |
| 84 | +After applying the PackageRepository definition above to your Kubernetes cluster, you will be able to check that the PackageRepository and |
| 85 | +its associated Packages were successfully deployed by checking the PackageRepository status: |
| 86 | + |
| 87 | +```bash |
| 88 | +$ kubectl get packagerepository/simple-package-repository |
| 89 | +``` |
| 90 | + |
| 91 | +You will see a message of `Reconcile Succeeded` in the `DESCRIPTION` column of the output from `kubectl` if the PackageRepository was deloyed |
| 92 | +successfully. You can also run `kubectl get packages` to see that all Packages were introduced successfully. |
0 commit comments