Skip to content

Commit 50669ab

Browse files
grantmillergrantmiller
authored
Merge pull request #2737 from replicatedhq/helm-airgap-download
Helm airgap download instructions
2 parents 6d93bfe + 5c967eb commit 50669ab

File tree

8 files changed

+6052
-431
lines changed

8 files changed

+6052
-431
lines changed

‎docs/partials/helm/_helm-install-prereqs.mdx‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
* You must have a customer in the Replicated Vendor Portal with a valid email address. This email address is only used as a username for the Replicated registry and is never contacted. For more information about creating and editing customers in the Vendor Portal, see [Creating a Customer](/vendor/releases-creating-customer).
2+
3+
* To ensure that the Replicated proxy registry can be used to grant proxy access to your application images during Helm installations, you must create an image pull secret for the proxy registry and add it to your Helm chart. To do so, follow the steps in [Using the Proxy Registry with Helm Installations](/vendor/helm-image-registry).
4+
5+
* (Recommended) To install the Replicated SDK alongside the application, declare the SDK as a dependency. For more information, see [Install the SDK as a Subchart](replicated-sdk-installing#install-the-sdk-as-a-subchart) in _Installing the Replicated SDK_.

‎docs/vendor/helm-install-airgap.mdx‎

Lines changed: 103 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,103 @@
1+
import Prerequisites from "../partials/helm/_helm-install-prereqs.mdx"
2+
3+
# Installing and Updating with Helm in Air Gap Environments (Alpha)
4+
5+
:::note
6+
Air gap Helm installations are an Alpha feature. If you are interested in trying Helm air gap installations and providing feedback, please reach out to your account rep to enable this feature.
7+
:::
8+
9+
## Overview
10+
11+
Replicated supports installing and updating Helm charts in air gap environments with no outbound internet access. In air gap Helm installations, customers are guided through the process with instructions provided in the [Replicated Download Portal](/vendor/releases-share-download-portal).
12+
13+
When air gap Helm installations are enabled, an **Existing cluster with Helm** option is displayed in the Download Portal on the left nav. When selected, **Existing cluster with Helm** displays three tabs (**Install**, **Manual Update**, **Automate Updates**), as shown in the screenshot below:
14+
15+
![download helm option](/images/download-helm.png)
16+
17+
[View a larger version of this image](/images/download-helm.png)
18+
19+
Each tab provides instructions for how to install, perform a manual update, or configure automatic updates, respectively.
20+
21+
These installing and updating instructions assume that your customer is accessing the Download Portal from a workstation that can access the internet and their internal private registry. Direct access to the target cluster is not required.
22+
23+
Each method assumes that your customer is familiar with `curl`, `docker`, `helm`, `kubernetes`, and a bit of `bash`, particularly for automating updates.
24+
25+
## Prerequisites
26+
27+
Before you install, complete the following prerequisites:
28+
29+
* Reach out to your account rep to enable the Helm air gap installation feature.
30+
31+
<Prerequisites/>
32+
33+
## Install
34+
35+
The installation instructions provided in the Download Portal are designed to walk your customer through the first installation of your chart in an air gap environment.
36+
37+
To install with Helm in an air gap environment:
38+
39+
1. In the [Vendor Portal](https://vendor.replicated.com), go to **Customers > [Customer Name] > Reporting**.
40+
41+
1. In the **Download portal** section, click **Visit download portal** to log in to the Download Portal for the customer.
42+
43+
1. In the Download Portal left nav, click **Existing cluster with Helm**.
44+
45+
![download helm option](/images/download-helm.png)
46+
47+
[View a larger version of this image](/images/download-helm.png)
48+
49+
1. On the **Install** tab, in the **App version** dropdown, select the target application version to install.
50+
51+
1. Run the first command to authenticate into the Replicated proxy registry with the customer's credentials (the `license_id`).
52+
53+
1. Under **Get the list of images**, run the command provided to generate the list of images needed to install.
54+
55+
1. For **(Optional) Specify registry URI**, provide the URI for an internal image registry where you want to push images. If a registry URI is provided, Replicatd automatically updates the commands for tagging and pushing images with the URI.
56+
57+
1. For **Pull, tag, and push each image to your private registry**, copy and paste the docker commands provided to pull, tag, and push each image to your internal registry.
58+
59+
:::note
60+
If you did not provide a URI in the previous step, ensure that you manually replace the image names in the `tag` and `push` commands with the target registry URI.
61+
:::
62+
63+
1. Run the command to authenticate into the OCI registry that contains your Helm chart.
64+
65+
1. Run the command to install the `preflight` plugin. This allows you to run preflight checks before installing to ensure that the installation environment meets the requirements for the application.
66+
67+
1. For **Determine install method**, select one of the options depending on your ability to access the internet and the cluster from your workstation.
68+
69+
1. Run the `helm show values` command to download the default `values.yaml`. Then, edit the values as required.
70+
71+
:::note
72+
Replicated recommends that vendors provide detailed documentation that describes the values that customers need to configure.
73+
:::
74+
75+
1. Finally, use the commands provided and the edited `values.yaml` to run preflight checks and install the release with Helm.
76+
77+
## Perform Updates
78+
79+
This section describes the processes of performing manual and automatic updates with Helm in air gap environments using the instructions provided in the Download Portal.
80+
81+
### Manual Updates
82+
83+
The manual update instructions provided in the Download Portal are similar to the installation instructions.
84+
85+
However, the first step prompts the customer to select their current version an the target version to install. This step takes [required releases](/vendor/releases-about#properties) into consideration, thereby guiding the customer to the versions that are upgradable from their current version.
86+
87+
The additional steps are consistent with installation process until the `preflight` and `install` commands where customers provide the existing values from the cluster with the `helm get values` and `--reuse-values` commands.
88+
89+
If the new version introduces new images or other values, Replicated recommends that you explain this at the top of your release notes so that customers know they will need to make additional edits to the `values.yaml` before installing.
90+
91+
### Automate Updates
92+
93+
The instructions in the Download Portal for automating updates use API endpoints that your customers can automate against.
94+
95+
The instructions in the Download Portal provide customers with example commands that can be put into a script that they run periodically (nightly, weekly) using GitHub Actions, Jenkins, or other platforms.
96+
97+
This method assumes that the customer has already done a successful manual installation, including the configuration of the appropriate `values`.
98+
99+
After logging into the registry, the customer exports their current version and uses that to query an endpoint that provides the latest installable version number (either the next required release, or the latest release) and export it as the target version. With the target version, they can now query an API for the list of images.
100+
101+
With the list of images the provided `bash` script will automate the process of pulling updated images from the repository, tagging them with a name for an internal registry, and then pushing the newly tagged images to their internal registry.
102+
103+
With the assumption that the customer has set up the `values` to preserve the updated tag, they should now be able to login to the OCI registry and perform the commands to install the updated chart.

‎docs/vendor/helm-install-overview.mdx‎

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
import HelmDiagramOverview from "../partials/helm/_helm-diagram-overview.mdx"
2+
import Helm from "../partials/helm/_helm-definition.mdx"
3+
4+
# About Helm Installations with Replicated
5+
6+
This topic provides an introduction to Helm installations for applications distributed with Replicated.
7+
8+
## Overview
9+
10+
<Helm/>
11+
12+
Replicated strongly recommends that all applications are packaged using Helm because many enterprise users expect to be able to install an application with the Helm CLI.
13+
14+
Existing releases in the Replicated Platform that already support installation with Replicated KOTS and Replicated Embedded Cluster (and that include one or more Helm charts) can also be installed with the Helm CLI; it is not necessary to create and manage separate releases or channels for each installation method.
15+
16+
The following diagram shows how Helm charts distributed with Replicated are installed with Helm in online (internet-connected) customer environments:
17+
18+
<img src="/images/helm-install-diagram.png" alt="diagram of a helm chart in a custom environment" width="700px"/>
19+
20+
[View a larger version of this image](/images/helm-install-diagram.png)
21+
22+
<HelmDiagramOverview/>
23+
24+
For information about how to install with Helm, see:
25+
* [Installing with Helm](/vendor/install-with-helm)
26+
* [Installing and Updating with Helm in Air Gap Environments (Alpha)](helm-install-airgap)
27+
28+
## About the `global.replicated` Helm Values
29+
30+
When a customer installs your Helm chart from the Replicated registry, the Replicated registry injects values into the `global.replicated` field of the Helm chart values file.
31+
32+
The following is an example of a Helm values file containing the `global.replicated` field injected by the Replicated registry:
33+
34+
```yaml
35+
# Helm values.yaml
36+
global:
37+
replicated:
38+
channelName: Stable
39+
customerEmail: [email protected]
40+
customerName: Example Customer
41+
dockerconfigjson: eyJhdXRocyI6eyJd1dIRk5NbEZFVGsxd2JGUmFhWGxYWm5scloyNVRSV1pPT2pKT2NGaHhUVEpSUkU1...
42+
licenseFields:
43+
expires_at:
44+
description: License Expiration
45+
name: expires_at
46+
signature:
47+
v1: iZBpESXx7fpdtnbMKingYHiJH42rP8fPs0x8izy1mODckGBwVoA...
48+
title: Expiration
49+
value: "2023-05-30T00:00:00Z"
50+
valueType: String
51+
licenseID: YiIXRTjiB7R...
52+
licenseType: dev
53+
```
54+
55+
The values in the `global.replicated` field provide information about the following:
56+
* Details about the fields in the customer's license, such as the field name, description, signature, value, and any custom license fields that you define. You can use this license information to check license entitlments before the application is installed. For more information, see [Checking Entitlements in Helm Charts Before Deployment](/vendor/licenses-reference-helm).
57+
* A base64 encoded Docker configuration file. To proxy images from an external private registry with the Replicated proxy registry, you can use the `global.replicated.dockerconfigjson` field to create an image pull secret for the proxy registry. For more information, see [Proxying Images for Helm Installations](/vendor/helm-image-registry).
58+
59+
## Limitations
60+
61+
Helm installations have the following limitations:
62+
63+
* Installing with Helm in air gap environments is an Alpha feature. For more information, see [Installing and Updating with Helm in Air Gap Environments](/vendor/helm-install-airgap).
64+
* Helm CLI installations do not provide access to any of the features of the Replicated KOTS installer, such as:
65+
* The KOTS Admin Console
66+
* Strict preflight checks that block installation
67+
* Backup and restore with snapshots
68+
* Required releases with the **Prevent this release from being skipped during upgrades** option

‎docs/vendor/install-with-helm.md‎

Lines changed: 2 additions & 53 deletions
Original file line numberDiff line numberDiff line change
@@ -1,65 +1,14 @@
1-
import HelmDiagramOverview from "../partials/helm/_helm-diagram-overview.mdx"
1+
import Prerequisites from "../partials/helm/_helm-install-prereqs.mdx"
22

33
# Installing with Helm
44

55
This topic describes how to use Helm to install releases that contain one or more Helm charts. For more information about the `helm install` command, including how to override values in a chart during installation, see [Helm Install](https://helm.sh/docs/helm/helm_install/) in the Helm documentation.
66

7-
## Overview
8-
9-
The following diagram shows how Helm charts distributed with Replicated are installed with Helm in customer environments:
10-
11-
<img src="/images/helm-install-diagram.png" alt="diagram of a helm chart in a custom environment" width="700px"/>
12-
13-
[View a larger version of this image](/images/helm-install-diagram.png)
14-
15-
<HelmDiagramOverview/>
16-
17-
### Replicated Helm Values
18-
19-
When a customer installs your Helm chart from the Replicated registry, the Replicated registry injects values into the `global.replicated` field of the Helm chart values file.
20-
21-
The following is an example of a Helm values file containing the `global.replicated` field injected by the Replicated registry:
22-
23-
```yaml
24-
# Helm values.yaml
25-
global:
26-
replicated:
27-
channelName: Stable
28-
customerEmail: [email protected]
29-
customerName: Example Customer
30-
dockerconfigjson: eyJhdXRocyI6eyJd1dIRk5NbEZFVGsxd2JGUmFhWGxYWm5scloyNVRSV1pPT2pKT2NGaHhUVEpSUkU1...
31-
licenseFields:
32-
expires_at:
33-
description: License Expiration
34-
name: expires_at
35-
signature:
36-
v1: iZBpESXx7fpdtnbMKingYHiJH42rP8fPs0x8izy1mODckGBwVoA...
37-
title: Expiration
38-
value: "2023-05-30T00:00:00Z"
39-
valueType: String
40-
licenseID: YiIXRTjiB7R...
41-
licenseType: dev
42-
```
43-
44-
The values in the `global.replicated` field provide information about the following:
45-
* Details about the fields in the customer's license, such as the field name, description, signature, value, and any custom license fields that you define. You can use this license information to check license entitlments before the application is installed. For more information, see [Checking Entitlements in Helm Charts Before Deployment](/vendor/licenses-reference-helm).
46-
* A base64 encoded Docker configuration file. To proxy images from an external private registry with the Replicated proxy registry, you can use the `global.replicated.dockerconfigjson` field to create an image pull secret for the proxy registry. For more information, see [Proxying Images for Helm Installations](/vendor/helm-image-registry).
47-
48-
### Limitations
49-
50-
Helm CLI installations do not provide access to any of the features of the Replicated KOTS installer, such as:
51-
* Air gap bundles for installations into air gapped environments
52-
* The KOTS Admin Console
53-
* Strict preflight checks that block installation
54-
* Backup and restore with snapshots
55-
* Required releases with the **Prevent this release from being skipped during upgrades** option
56-
577
## Prerequisites
588

599
Before you install, complete the following prerequisites:
6010

61-
* You must have a customer in the Replicated Vendor Portal with a valid email address. This email address is only used as a username for the Replicated registry and is never contacted. For more information about creating and editing customers in the Vendor Portal, see [Creating a Customer](/vendor/releases-creating-customer).
62-
* (Recommended) To install the Replicated SDK alongside the application, declare the SDK as a dependency. For more information, see [Install the SDK as a Subchart](replicated-sdk-installing#install-the-sdk-as-a-subchart) in _Installing the Replicated SDK_.
11+
<Prerequisites/>
6312

6413
## Install
6514

‎package.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,7 @@
2222
"@types/node": "18.15.11",
2323
"@types/react": "18.3.5",
2424
"clsx": "^2.1.0",
25+
"docusaurus": "^1.14.7",
2526
"loader-utils": "3.3.1",
2627
"prism-react-renderer": "^2.3.0",
2728
"react": "^18.2.0",

‎sidebars.js‎

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -488,7 +488,15 @@ const sidebars = {
488488
'reference/cron-expressions',
489489
],
490490
},
491-
'vendor/install-with-helm',
491+
{
492+
type: 'category',
493+
label: 'Installing with Helm',
494+
items: [
495+
'vendor/helm-install-overview',
496+
'vendor/install-with-helm',
497+
'vendor/helm-install-airgap',
498+
],
499+
},
492500
{
493501
type: 'category',
494502
label: 'Replicated SDK (Beta)',

‎static/images/download-helm.png‎

193 KB
Loading

0 commit comments

Comments
 (0)