Skip to content

Commit d480e68

Browse files
paigecalvertpaigecalvert
committed
docs edits
1 parent e8dc41d commit d480e68

File tree

5 files changed

+178
-91
lines changed

5 files changed

+178
-91
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: 97 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,97 @@
1+
import Prerequisites from "../partials/helm/_helm-install-prereqs.mdx"
2+
3+
# Installing and Updating with Helm in an Air Gap Environment (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+
* Reached 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. In the **App version** dropdown, select the target application version to install.
50+
51+
1. On the **Install** tab, 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**, for each image in the list, run the corresponding `docker` `pull`, `tag`, and `push` commands provided.
54+
55+
:::note
56+
If customers provided their own registry URI, Replicatd pre-configures these commands. Otherwise, customers need to manually replace the image names in the `tag` and `push` commands.
57+
:::
58+
59+
1. Run the next command to authenticate into the OCI registry that contains your Helm chart, and then install the `preflight` plugin.
60+
61+
1. Get the default `values.yaml` and edit it as required. Customers will edit the Helm values to meet their environment's configuration needs.
62+
63+
:::note
64+
Replicated recommends that vendors provide detailed documentation that describes the values that customers need to configure.
65+
:::
66+
67+
1. Finally, specify how to access the cluster and then use the corresponding commands and edited `values.yaml` to run preflight checks and install the chart.
68+
69+
## Perform Updates
70+
71+
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.
72+
73+
### Manual Updates
74+
75+
The manual update instructions provided in the Download Portal are similar to the installation instructions.
76+
77+
However, the first step prompts the customer to select their current version an the target version to install.
78+
79+
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.
80+
81+
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.
82+
83+
Should you introduce new images, or other values, you should call this out at the top of your release notes so that customers know they will need to make additional edits to the `values.yaml` before installing.
84+
85+
### Automate Updates
86+
87+
The automate update instructions rely on a few new API endpoints that your customers can automate against.
88+
89+
The instructions in the Download Portal provide customers with example commands that can be put into a script that they run periodically (as in, nightly or weekly) using GitHub Actions, Jenkins etc.
90+
91+
This method assumes that the customer has already done a successful manual installation, including the configuration of the appropriate `values`.
92+
93+
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.
94+
95+
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.
96+
97+
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: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
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+
## About the `global.replicated` Helm Values
25+
26+
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.
27+
28+
The following is an example of a Helm values file containing the `global.replicated` field injected by the Replicated registry:
29+
30+
```yaml
31+
# Helm values.yaml
32+
global:
33+
replicated:
34+
channelName: Stable
35+
customerEmail: [email protected]
36+
customerName: Example Customer
37+
dockerconfigjson: eyJhdXRocyI6eyJd1dIRk5NbEZFVGsxd2JGUmFhWGxYWm5scloyNVRSV1pPT2pKT2NGaHhUVEpSUkU1...
38+
licenseFields:
39+
expires_at:
40+
description: License Expiration
41+
name: expires_at
42+
signature:
43+
v1: iZBpESXx7fpdtnbMKingYHiJH42rP8fPs0x8izy1mODckGBwVoA...
44+
title: Expiration
45+
value: "2023-05-30T00:00:00Z"
46+
valueType: String
47+
licenseID: YiIXRTjiB7R...
48+
licenseType: dev
49+
```
50+
51+
The values in the `global.replicated` field provide information about the following:
52+
* 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).
53+
* 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).
54+
55+
## Limitations
56+
57+
Helm installations have the following limitations:
58+
59+
* 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).
60+
* Helm CLI installations do not provide access to any of the features of the Replicated KOTS installer, such as:
61+
* The KOTS Admin Console
62+
* Strict preflight checks that block installation
63+
* Backup and restore with snapshots
64+
* Required releases with the **Prevent this release from being skipped during upgrades** option

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

Lines changed: 3 additions & 90 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

@@ -110,40 +59,4 @@ To install a Helm chart:
11059
**Example**:
11160

11261
![example customer in the Vendor Portal with an active instance](/images/sdk-customer-active-example.png)
113-
[View a larger version of this image](/images/sdk-customer-active-example.png)
114-
115-
116-
## Helm installs for Airgap Environments (Alpha)
117-
Replicated supports installing and updating Helm charts in Airgapped environments and guiding end customers through the process with the [Download Portal](/vendor/releases-share-download-portal). Please ask your account rep to enable this feature if you're interested in trying it and providing feedback.
118-
119-
When this feature is enabled, a new option will be displayed for the Download Portal on the left nav, that when selected, will display 3 tabs (Install, Manual Update, Automate Updates):
120-
![download helm option](/images/download-helm.png)
121-
122-
Each of these instruction sets assumes 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. Each method assumes that your customer is familiar with `curl`, `docker`, `helm`, `kubernetes`, and a bit of `bash`, particularly for automate.
123-
124-
### Install
125-
The install instructions are designed to walk your customer through the first installation of your chart in a disconnected environment.
126-
They'll be presented with credentials (the license_id) to authenticate into the proxy registry that Replicated manages for you.
127-
From there, we present them with the full list of images and the corresponding `docker` `pull`, `tag`, and `push` commands for each.
128-
If they've provided their registry URI, we pre-configure the commands, else they'll need to manually replace the image names in the `tag` and `push` commands.
129-
Next they'll authenticate into the OCI registry that contains your Helm chart, and then install the `preflight` plugin.
130-
In the next steps, they'll get your default `values.yaml` and edit it to meet their environment's configuration needs.
131-
We recommend that your accompanying documentation include detailed instructions on what values they need to configure.
132-
Finally, your customer will specify how they access their cluster and then use the corresponding commands and their edited `values.yaml` to run the Preflight Checks and install the chart.
133-
134-
### Manual Updates
135-
The manual update instructions follow closely with the install instructions.
136-
However, the first step prompts the customer to select their current version and target version to install.
137-
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.
138-
The additional steps are very consistent with install process until the `preflight` and `install` commands where we need to get the existing values from the cluster with the `helm get values` and `--reuse-values` commands.
139-
Should you introduce new images, or other values, you should call this out at the top of your release notes so that customers know they will need to make additional edits to the `values.yaml` before installing.
140-
141-
### Automate Updates
142-
The automate update instructions rely on a few new API endpoints that your customers can automate against.
143-
We provide each customer with example commands that can be put into a script that they run periodically (i.e. nightly, weekly) via GitHub Actions, Jenkins etc.
144-
This method assumes that the customer has already done a successful manual installation, including the configuration the appropriate `values`.
145-
146-
After logging into the registry, we have the customer export their current version and use 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.
147-
With the target version, they can now query an API for the list of images.
148-
With this 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.
149-
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.
62+
[View a larger version of this image](/images/sdk-customer-active-example.png)

‎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)',

0 commit comments

Comments
 (0)