mirror of
https://github.com/rancher/rancher-docs.git
synced 2026-09-26 04:58:07 +00:00
Apply Divio and update links
This commit is contained in:
Billy Tat
+38
@@ -0,0 +1,38 @@
|
||||
---
|
||||
title: Adding TLS Secrets
|
||||
weight: 2
|
||||
---
|
||||
|
||||
Kubernetes will create all the objects and services for Rancher, but it will not become available until we populate the `tls-rancher-ingress` secret in the `cattle-system` namespace with the certificate and key.
|
||||
|
||||
Combine the server certificate followed by any intermediate certificate(s) needed into a file named `tls.crt`. Copy your certificate key into a file named `tls.key`.
|
||||
|
||||
For example, [acme.sh](https://acme.sh) provides server certificate and CA chains in `fullchain.cer` file.
|
||||
This `fullchain.cer` should be renamed to `tls.crt` & certificate key file as `tls.key`.
|
||||
|
||||
Use `kubectl` with the `tls` secret type to create the secrets.
|
||||
|
||||
```
|
||||
kubectl -n cattle-system create secret tls tls-rancher-ingress \
|
||||
--cert=tls.crt \
|
||||
--key=tls.key
|
||||
```
|
||||
|
||||
> **Note:** If you want to replace the certificate, you can delete the `tls-rancher-ingress` secret using `kubectl -n cattle-system delete secret tls-rancher-ingress` and add a new one using the command shown above. If you are using a private CA signed certificate, replacing the certificate is only possible if the new certificate is signed by the same CA as the certificate currently in use.
|
||||
|
||||
# Using a Private CA Signed Certificate
|
||||
|
||||
If you are using a private CA, Rancher requires a copy of the CA certificate which is used by the Rancher Agent to validate the connection to the server.
|
||||
|
||||
Copy the CA certificate into a file named `cacerts.pem` and use `kubectl` to create the `tls-ca` secret in the `cattle-system` namespace.
|
||||
|
||||
```
|
||||
kubectl -n cattle-system create secret generic tls-ca \
|
||||
--from-file=cacerts.pem=./cacerts.pem
|
||||
```
|
||||
|
||||
> **Note:** The configured `tls-ca` secret is retrieved when Rancher starts. On a running Rancher installation the updated CA will take effect after new Rancher pods are started.
|
||||
|
||||
# Updating a Private CA Certificate
|
||||
|
||||
Follow the steps on [this page](update-rancher-certificate.md) to update the SSL certificate of the ingress in a Rancher [high availability Kubernetes installation](../../../pages-for-subheaders/install-upgrade-on-a-kubernetes-cluster.md) or to switch from the default self-signed certificate to a custom certificate.
|
||||
+105
@@ -0,0 +1,105 @@
|
||||
---
|
||||
title: Choosing a Rancher Version
|
||||
weight: 1
|
||||
aliases:
|
||||
- /rancher/v2.0-v2.4/en/installation/options/server-tags
|
||||
---
|
||||
|
||||
import Tabs from '@theme/Tabs';
|
||||
import TabItem from '@theme/TabItem';
|
||||
|
||||
This section describes how to choose a Rancher version.
|
||||
|
||||
For a high-availability installation of Rancher, which is recommended for production, the Rancher server is installed using a **Helm chart** on a Kubernetes cluster. Refer to the [Helm version requirements](installation/options/helm-version) to choose a version of Helm to install Rancher.
|
||||
|
||||
For Docker installations of Rancher, which is used for development and testing, you will install Rancher as a **Docker image.**
|
||||
|
||||
<Tabs>
|
||||
<TabItem value="Helm Charts">
|
||||
|
||||
When installing, upgrading, or rolling back Rancher Server when it is [installed on a Kubernetes cluster](../../../pages-for-subheaders/install-upgrade-on-a-kubernetes-cluster.md), Rancher server is installed using a Helm chart on a Kubernetes cluster. Therefore, as you prepare to install or upgrade a high availability Rancher configuration, you must add a Helm chart repository that contains the charts for installing Rancher.
|
||||
|
||||
Refer to the [Helm version requirements](installation/options/helm-version) to choose a version of Helm to install Rancher.
|
||||
|
||||
### Helm Chart Repositories
|
||||
|
||||
Rancher provides several different Helm chart repositories to choose from. We align our latest and stable Helm chart repositories with the Docker tags that are used for a Docker installation. Therefore, the `rancher-latest` repository will contain charts for all the Rancher versions that have been tagged as `rancher/rancher:latest`. When a Rancher version has been promoted to the `rancher/rancher:stable`, it will get added to the `rancher-stable` repository.
|
||||
|
||||
| Type | Command to Add the Repo | Description of the Repo |
|
||||
| -------------- | ------------ | ----------------- |
|
||||
| rancher-latest | `helm repo add rancher-latest https://releases.rancher.com/server-charts/latest` | Adds a repository of Helm charts for the latest versions of Rancher. We recommend using this repo for testing out new Rancher builds. |
|
||||
| rancher-stable | `helm repo add rancher-stable https://releases.rancher.com/server-charts/stable` | Adds a repository of Helm charts for older, stable versions of Rancher. We recommend using this repo for production environments. |
|
||||
| rancher-alpha | `helm repo add rancher-alpha https://releases.rancher.com/server-charts/alpha` | Adds a repository of Helm charts for alpha versions of Rancher for previewing upcoming releases. These releases are discouraged in production environments. Upgrades _to_ or _from_ charts in the rancher-alpha repository to any other chart, regardless or repository, aren't supported. |
|
||||
|
||||
<br/>
|
||||
Instructions on when to select these repos are available below in [Switching to a Different Helm Chart Repository](#switching-to-a-different-helm-chart-repository).
|
||||
|
||||
> **Note:** The introduction of the `rancher-latest` and `rancher-stable` Helm Chart repositories was introduced after Rancher v2.1.0, so the `rancher-stable` repository contains some Rancher versions that were never marked as `rancher/rancher:stable`. The versions of Rancher that were tagged as `rancher/rancher:stable` before v2.1.0 are v2.0.4, v2.0.6, v2.0.8. Post v2.1.0, all charts in the `rancher-stable` repository will correspond with any Rancher version tagged as `stable`.
|
||||
|
||||
### Helm Chart Versions
|
||||
|
||||
Rancher Helm chart versions match the Rancher version (i.e `appVersion`). Once you've added the repo you can search it to show available versions with the following command:<br/>
|
||||
`helm search repo --versions`
|
||||
|
||||
If you have several repos you can specify the repo name, ie. `helm search repo rancher-stable/rancher --versions` <br/>
|
||||
For more information, see https://helm.sh/docs/helm/helm_search_repo/
|
||||
|
||||
To fetch a specific version of your chosen repo, define the `--version` parameter like in the following example:<br/>
|
||||
`helm fetch rancher-stable/rancher --version=2.4.8`
|
||||
|
||||
For the Rancher v2.1.x versions, there were some Helm charts where the version was a build number, i.e. `yyyy.mm.<build-number>`. These charts have been replaced with the equivalent Rancher version and are no longer available.
|
||||
|
||||
### Switching to a Different Helm Chart Repository
|
||||
|
||||
After installing Rancher, if you want to change which Helm chart repository to install Rancher from, you will need to follow these steps.
|
||||
|
||||
> **Note:** Because the rancher-alpha repository contains only alpha charts, switching between the rancher-alpha repository and the rancher-stable or rancher-latest repository for upgrades is not supported.
|
||||
|
||||
{{< release-channel >}}
|
||||
|
||||
1. List the current Helm chart repositories.
|
||||
|
||||
```plain
|
||||
helm repo list
|
||||
|
||||
NAME URL
|
||||
stable https://charts.helm.sh/stable
|
||||
rancher-<CHART_REPO> https://releases.rancher.com/server-charts/<CHART_REPO>
|
||||
```
|
||||
|
||||
2. Remove the existing Helm Chart repository that contains your charts to install Rancher, which will either be `rancher-stable` or `rancher-latest` depending on what you had initially added.
|
||||
|
||||
```plain
|
||||
helm repo remove rancher-<CHART_REPO>
|
||||
```
|
||||
|
||||
3. Add the Helm chart repository that you want to start installing Rancher from.
|
||||
|
||||
```plain
|
||||
helm repo add rancher-<CHART_REPO> https://releases.rancher.com/server-charts/<CHART_REPO>
|
||||
```
|
||||
|
||||
4. Continue to follow the steps to [upgrade Rancher](installation/upgrades-rollbacks/upgrades/ha) from the new Helm chart repository.
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="Docker Images">
|
||||
|
||||
When performing [Docker installs](installation/single-node), upgrades, or rollbacks, you can use _tags_ to install a specific version of Rancher.
|
||||
|
||||
### Server Tags
|
||||
|
||||
Rancher Server is distributed as a Docker image, which have tags attached to them. You can specify this tag when entering the command to deploy Rancher. Remember that if you use a tag without an explicit version (like `latest` or `stable`), you must explicitly pull a new version of that image tag. Otherwise, any image cached on the host will be used.
|
||||
|
||||
| Tag | Description |
|
||||
| -------------------------- | ------ |
|
||||
| `rancher/rancher:latest` | Our latest development release. These builds are validated through our CI automation framework. These releases are not recommended for production environments. |
|
||||
| `rancher/rancher:stable` | Our newest stable release. This tag is recommended for production. |
|
||||
| `rancher/rancher:<v2.X.X>` | You can install specific versions of Rancher by using the tag from a previous release. See what's available at DockerHub. |
|
||||
|
||||
> **Notes:**
|
||||
>
|
||||
> - The `master` tag or any tag with `-rc` or another suffix is meant for the Rancher testing team to validate. You should not use these tags, as these builds are not officially supported.
|
||||
> - Want to install an alpha review for preview? Install using one of the alpha tags listed on our [announcements page](https://forums.rancher.com/c/announcements) (e.g., `v2.2.0-alpha1`). Caveat: Alpha releases cannot be upgraded to or from any other release.
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
+28
@@ -0,0 +1,28 @@
|
||||
---
|
||||
title: About Custom CA Root Certificates
|
||||
weight: 1
|
||||
aliases:
|
||||
- /rancher/v2.0-v2.4/en/installation/options/custom-ca-root-certificate/
|
||||
- /rancher/v2.0-v2.4/en/installation/resources/choosing-version/encryption/custom-ca-root-certificate
|
||||
---
|
||||
|
||||
If you're using Rancher in an internal production environment where you aren't exposing apps publicly, use a certificate from a private certificate authority (CA).
|
||||
|
||||
Services that Rancher needs to access are sometimes configured with a certificate from a custom/internal CA root, also known as self signed certificate. If the presented certificate from the service cannot be validated by Rancher, the following error displays: `x509: certificate signed by unknown authority`.
|
||||
|
||||
To validate the certificate, the CA root certificates need to be added to Rancher. As Rancher is written in Go, we can use the environment variable `SSL_CERT_DIR` to point to the directory where the CA root certificates are located in the container. The CA root certificates directory can be mounted using the Docker volume option (`-v host-source-directory:container-destination-directory`) when starting the Rancher container.
|
||||
|
||||
Examples of services that Rancher can access:
|
||||
|
||||
- Catalogs
|
||||
- Authentication providers
|
||||
- Accessing hosting/cloud API when using Node Drivers
|
||||
|
||||
## Installing with the custom CA Certificate
|
||||
|
||||
For details on starting a Rancher container with your private CA certificates mounted, refer to the installation docs:
|
||||
|
||||
- [Docker install Custom CA certificate options](../../../reference-guides/single-node-rancher-in-docker/advanced-options.md#custom-ca-certificate)
|
||||
|
||||
- [Kubernetes install options for Additional Trusted CAs](../../../reference-guides/installation-references/helm-chart-options.md#additional-trusted-cas)
|
||||
|
||||
+17
@@ -0,0 +1,17 @@
|
||||
---
|
||||
title: Helm Version Requirements
|
||||
weight: 3
|
||||
aliases:
|
||||
- /rancher/v2.0-v2.4/en/installation/options/helm-version
|
||||
- /rancher/v2.0-v2.4/en/installation/options/helm2
|
||||
- /rancher/v2.0-v2.4/en/installation/options/helm2/helm-init
|
||||
- /rancher/v2.0-v2.4/en/installation/options/helm2/helm-rancher
|
||||
---
|
||||
|
||||
This section contains the requirements for Helm, which is the tool used to install Rancher on a high-availability Kubernetes cluster.
|
||||
|
||||
> The installation instructions have been updated for Helm 3. For migration of installs started with Helm 2, refer to the official [Helm 2 to 3 Migration Docs.](https://helm.sh/blog/migrate-from-helm-v2-to-helm-v3/) [This section](installation/options/helm2) provides a copy of the older high-availability Rancher installation instructions that used Helm 2, and it is intended to be used if upgrading to Helm 3 is not feasible.
|
||||
|
||||
- Helm v2.16.0 or higher is required for Kubernetes v1.16. For the default Kubernetes version, refer to the [release notes](https://github.com/rancher/rke/releases) for the version of RKE that you are using.
|
||||
- Helm v2.15.0 should not be used, because of an issue with converting/comparing numbers.
|
||||
- Helm v2.12.0 should not be used, because of an issue with `cert-manager`.
|
||||
+72
@@ -0,0 +1,72 @@
|
||||
---
|
||||
title: Setting up Local System Charts for Air Gapped Installations
|
||||
weight: 120
|
||||
aliases:
|
||||
- /rancher/v2.0-v2.4/en/installation/air-gap-single-node/config-rancher-system-charts/_index.md
|
||||
- /rancher/v2.0-v2.4/en/installation/air-gap-high-availability/config-rancher-system-charts/_index.md
|
||||
- /rancher/v2.0-v2.4/en/installation/options/local-system-charts
|
||||
---
|
||||
|
||||
import Tabs from '@theme/Tabs';
|
||||
import TabItem from '@theme/TabItem';
|
||||
|
||||
The [System Charts](https://github.com/rancher/system-charts) repository contains all the catalog items required for features such as monitoring, logging, alerting and global DNS.
|
||||
|
||||
In an air gapped installation of Rancher, you will need to configure Rancher to use a local copy of the system charts. This section describes how to use local system charts using a CLI flag in Rancher v2.3.0, and using a Git mirror for Rancher versions before v2.3.0.
|
||||
|
||||
# Using Local System Charts in Rancher v2.3.0
|
||||
|
||||
In Rancher v2.3.0, a local copy of `system-charts` has been packaged into the `rancher/rancher` container. To be able to use these features in an air gap install, you will need to run the Rancher install command with an extra environment variable, `CATTLE_SYSTEM_CATALOG=bundled`, which tells Rancher to use the local copy of the charts instead of attempting to fetch them from GitHub.
|
||||
|
||||
Example commands for a Rancher installation with a bundled `system-charts` are included in the [air gap Docker installation](installation/air-gap-single-node/install-rancher) instructions and the [air gap Kubernetes installation](installation/air-gap-high-availability/install-rancher/) instructions.
|
||||
|
||||
# Setting Up System Charts for Rancher Before v2.3.0
|
||||
|
||||
### A. Prepare System Charts
|
||||
|
||||
The [System Charts](https://github.com/rancher/system-charts) repository contains all the catalog items required for features such as monitoring, logging, alerting and global DNS. To be able to use these features in an air gap install, you will need to mirror the `system-charts` repository to a location in your network that Rancher can reach and configure Rancher to use that repository.
|
||||
|
||||
Refer to the release notes in the `system-charts` repository to see which branch corresponds to your version of Rancher.
|
||||
|
||||
### B. Configure System Charts
|
||||
|
||||
Rancher needs to be configured to use your Git mirror of the `system-charts` repository. You can configure the system charts repository either from the Rancher UI or from Rancher's API view.
|
||||
|
||||
<Tabs>
|
||||
<TabItem value="Rancher UI">
|
||||
|
||||
In the catalog management page in the Rancher UI, follow these steps:
|
||||
|
||||
1. Go to the **Global** view.
|
||||
|
||||
1. Click **Tools > Catalogs.**
|
||||
|
||||
1. The system chart is displayed under the name `system-library`. To edit the configuration of the system chart, click **⋮ > Edit.**
|
||||
|
||||
1. In the **Catalog URL** field, enter the location of the Git mirror of the `system-charts` repository.
|
||||
|
||||
1. Click **Save.**
|
||||
|
||||
**Result:** Rancher is configured to download all the required catalog items from your `system-charts` repository.
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="Rancher API">
|
||||
|
||||
1. Log into Rancher.
|
||||
|
||||
1. Open `https://<your-rancher-server>/v3/catalogs/system-library` in your browser.
|
||||
|
||||
|
||||
|
||||
1. Click **Edit** on the upper right corner and update the value for **url** to the location of the Git mirror of the `system-charts` repository.
|
||||
|
||||
|
||||
|
||||
1. Click **Show Request**
|
||||
|
||||
1. Click **Send Request**
|
||||
|
||||
**Result:** Rancher is configured to download all the required catalog items from your `system-charts` repository.
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
+234
@@ -0,0 +1,234 @@
|
||||
---
|
||||
title: Updating the Rancher Certificate
|
||||
weight: 10
|
||||
---
|
||||
|
||||
# Updating a Private CA Certificate
|
||||
|
||||
Follow these steps to update the SSL certificate of the ingress in a Rancher [high availability Kubernetes installation](../../../pages-for-subheaders/install-upgrade-on-a-kubernetes-cluster.md) or to switch from the default self-signed certificate to a custom certificate.
|
||||
|
||||
A summary of the steps is as follows:
|
||||
|
||||
1. Create or update the `tls-rancher-ingress` Kubernetes secret resource with the new certificate and private key.
|
||||
2. Create or update the `tls-ca` Kubernetes secret resource with the root CA certificate (only required when using a private CA).
|
||||
3. Update the Rancher installation using the Helm CLI.
|
||||
4. Reconfigure the Rancher agents to trust the new CA certificate.
|
||||
|
||||
The details of these instructions are below.
|
||||
|
||||
## 1. Create/update the certificate secret resource
|
||||
|
||||
First, concatenate the server certificate followed by any intermediate certificate(s) to a file named `tls.crt` and provide the corresponding certificate key in a file named `tls.key`.
|
||||
|
||||
If you are switching the install from using the Rancher self-signed certificate or Let’s Encrypt issued certificates, use the following command to create the `tls-rancher-ingress` secret resource in your Rancher HA cluster:
|
||||
|
||||
```
|
||||
$ kubectl -n cattle-system create secret tls tls-rancher-ingress \
|
||||
--cert=tls.crt \
|
||||
--key=tls.key
|
||||
```
|
||||
|
||||
Alternatively, to update an existing certificate secret:
|
||||
|
||||
```
|
||||
$ kubectl -n cattle-system create secret tls tls-rancher-ingress \
|
||||
--cert=tls.crt \
|
||||
--key=tls.key \
|
||||
--dry-run --save-config -o yaml | kubectl apply -f -
|
||||
```
|
||||
|
||||
## 2. Create/update the CA certificate secret resource
|
||||
|
||||
If the new certificate was signed by a private CA, you will need to copy the corresponding root CA certificate into a file named `cacerts.pem` and create or update the `tls-ca secret` in the `cattle-system` namespace. If the certificate was signed by an intermediate CA, then the `cacerts.pem` must contain both the intermediate and root CA certificates (in this order).
|
||||
|
||||
To create the initial secret:
|
||||
|
||||
```
|
||||
$ kubectl -n cattle-system create secret generic tls-ca \
|
||||
--from-file=cacerts.pem
|
||||
```
|
||||
|
||||
To update an existing `tls-ca` secret:
|
||||
|
||||
```
|
||||
$ kubectl -n cattle-system create secret generic tls-ca \
|
||||
--from-file=cacerts.pem \
|
||||
--dry-run --save-config -o yaml | kubectl apply -f -
|
||||
```
|
||||
|
||||
## 3. Reconfigure the Rancher deployment
|
||||
|
||||
> Before proceeding, [generate an API token in the Rancher UI](../../../reference-guides/user-settings/api-keys.md#creating-an-api-key) (<b>User > API & Keys</b>).
|
||||
|
||||
This step is required if Rancher was initially installed with self-signed certificates (`ingress.tls.source=rancher`) or with a Let's Encrypt issued certificate (`ingress.tls.source=letsEncrypt`).
|
||||
|
||||
It ensures that the Rancher pods and ingress resources are reconfigured to use the new server and optional CA certificate.
|
||||
|
||||
To update the Helm deployment you will need to use the same (`--set`) options that were used during initial installation. Check with:
|
||||
|
||||
```
|
||||
$ helm get values rancher -n cattle-system
|
||||
```
|
||||
|
||||
Also get the version string of the currently deployed Rancher chart:
|
||||
|
||||
```
|
||||
$ helm ls -A
|
||||
```
|
||||
|
||||
Upgrade the Helm application instance using the original configuration values and making sure to specify `ingress.tls.source=secret` as well as the current chart version to prevent an application upgrade.
|
||||
|
||||
If the certificate was signed by a private CA, add the `set privateCA=true` argument as well. Also make sure to read the documentation describing the initial installation using custom certificates.
|
||||
|
||||
```
|
||||
helm upgrade rancher rancher-stable/rancher \
|
||||
--namespace cattle-system \
|
||||
--version <DEPLOYED_CHART_VERSION> \
|
||||
--set hostname=rancher.my.org \
|
||||
--set ingress.tls.source=secret \
|
||||
--set ...
|
||||
```
|
||||
|
||||
When the upgrade is completed, navigate to `https://<Rancher_SERVER>/v3/settings/cacerts` to verify that the value matches the CA certificate written in the `tls-ca` secret earlier.
|
||||
|
||||
## 4. Reconfigure Rancher agents to trust the private CA
|
||||
|
||||
This section covers three methods to reconfigure Rancher agents to trust the private CA. This step is required if either of the following is true:
|
||||
|
||||
- Rancher was initially configured to use the Rancher self-signed certificate (`ingress.tls.source=rancher`) or with a Let's Encrypt issued certificate (`ingress.tls.source=letsEncrypt`)
|
||||
- The root CA certificate for the new custom certificate has changed
|
||||
|
||||
### Why is this step required?
|
||||
|
||||
When Rancher is configured with a certificate signed by a private CA, the CA certificate chain is downloaded into Rancher agent containers. Agents compare the checksum of the downloaded certificate against the `CATTLE_CA_CHECKSUM` environment variable. This means that, when the private CA certificate is changed on Rancher server side, the environvment variable `CATTLE_CA_CHECKSUM` must be updated accordingly.
|
||||
|
||||
### Which method should I choose?
|
||||
|
||||
Method 1 is the easiest one but requires all clusters to be connected to Rancher after the certificates have been rotated. This is usually the case if the process is performed right after updating the Rancher deployment (Step 3).
|
||||
|
||||
If the clusters have lost connection to Rancher but you have [Authorized Cluster Endpoints](https://rancher.com/docs/rancher/v2.0-v2.4/en/cluster-admin/cluster-access/ace/) enabled, then go with method 2.
|
||||
|
||||
Method 3 can be used as a fallback if method 1 and 2 are unfeasible.
|
||||
|
||||
### Method 1: Kubectl command
|
||||
|
||||
For each cluster under Rancher management (including `local`) run the following command using the Kubeconfig file of the Rancher management cluster (RKE or K3S).
|
||||
|
||||
```
|
||||
kubectl patch clusters <REPLACE_WITH_CLUSTERID> -p '{"status":{"agentImage":"dummy"}}' --type merge
|
||||
```
|
||||
|
||||
This command will cause all Agent Kubernetes resources to be reconfigured with the checksum of the new certificate.
|
||||
|
||||
|
||||
### Method 2: Manually update checksum
|
||||
|
||||
Manually patch the agent Kubernetes resources by updating the `CATTLE_CA_CHECKSUM` environment variable to the value matching the checksum of the new CA certificate. Generate the new checksum value like so:
|
||||
|
||||
```
|
||||
$ curl -k -s -fL <RANCHER_SERVER>/v3/settings/cacerts | jq -r .value > cacert.tmp
|
||||
$ sha256sum cacert.tmp | awk '{print $1}'
|
||||
```
|
||||
|
||||
Using a Kubeconfig for each downstream cluster update the environment variable for the two agent deployments.
|
||||
|
||||
```
|
||||
$ kubectl edit -n cattle-system ds/cattle-node-agent
|
||||
$ kubectl edit -n cattle-system deployment/cluster-agent
|
||||
```
|
||||
|
||||
### Method 3: Recreate Rancher agents
|
||||
|
||||
With this method you are recreating the Rancher agents by running a set of commands on a controlplane node of each downstream cluster.
|
||||
|
||||
First, generate the agent definitions as described here: https://gist.github.com/superseb/076f20146e012f1d4e289f5bd1bd4971
|
||||
|
||||
Then, connect to a controlplane node of the downstream cluster via SSH, create a Kubeconfig and apply the definitions:
|
||||
https://gist.github.com/superseb/b14ed3b5535f621ad3d2aa6a4cd6443b
|
||||
|
||||
# Updating from a Private CA Certificate to a Common Certificate
|
||||
|
||||
>It is possible to perform the opposite procedure as shown above: you may change from a private certificate to a common, or non-private, certificate. The steps involved are outlined below.
|
||||
|
||||
## 1. Create/update the certificate secret resource
|
||||
|
||||
First, concatenate the server certificate followed by any intermediate certificate(s) to a file named `tls.crt` and provide the corresponding certificate key in a file named `tls.key`.
|
||||
|
||||
If you are switching the install from using the Rancher self-signed certificate or Let’s Encrypt issued certificates, use the following command to create the `tls-rancher-ingress` secret resource in your Rancher HA cluster:
|
||||
|
||||
```
|
||||
$ kubectl -n cattle-system create secret tls tls-rancher-ingress \
|
||||
--cert=tls.crt \
|
||||
--key=tls.key
|
||||
```
|
||||
|
||||
Alternatively, to update an existing certificate secret:
|
||||
|
||||
```
|
||||
$ kubectl -n cattle-system create secret tls tls-rancher-ingress \
|
||||
--cert=tls.crt \
|
||||
--key=tls.key \
|
||||
--dry-run --save-config -o yaml | kubectl apply -f -
|
||||
```
|
||||
|
||||
## 2. Delete the CA certificate secret resource
|
||||
|
||||
You will delete the `tls-ca secret` in the `cattle-system` namespace as it is no longer needed. You may also optionally save a copy of the `tls-ca secret` if desired.
|
||||
|
||||
To save the existing secret:
|
||||
|
||||
```
|
||||
kubectl -n cattle-system get secret tls-ca -o yaml > tls-ca.yaml
|
||||
```
|
||||
|
||||
To delete the existing `tls-ca` secret:
|
||||
|
||||
```
|
||||
kubectl -n cattle-system delete secret tls-ca
|
||||
```
|
||||
|
||||
## 3. Reconfigure the Rancher deployment
|
||||
|
||||
> Before proceeding, [generate an API token in the Rancher UI](https://rancher.com/docs/rancher/v2.6/en/user-settings/api-keys/#creating-an-api-key) (<b>User > API & Keys</b>) and save the Bearer Token which you might need in step 4.
|
||||
|
||||
This step is required if Rancher was initially installed with self-signed certificates (`ingress.tls.source=rancher`) or with a Let's Encrypt issued certificate (`ingress.tls.source=letsEncrypt`).
|
||||
|
||||
It ensures that the Rancher pods and ingress resources are reconfigured to use the new server and optional CA certificate.
|
||||
|
||||
To update the Helm deployment you will need to use the same (`--set`) options that were used during initial installation. Check with:
|
||||
|
||||
```
|
||||
$ helm get values rancher -n cattle-system
|
||||
```
|
||||
|
||||
Also get the version string of the currently deployed Rancher chart:
|
||||
|
||||
```
|
||||
$ helm ls -A
|
||||
```
|
||||
|
||||
Upgrade the Helm application instance using the original configuration values and making sure to specify the current chart version to prevent an application upgrade.
|
||||
|
||||
Also make sure to read the documentation describing the initial installation using custom certificates.
|
||||
|
||||
```
|
||||
helm upgrade rancher rancher-stable/rancher \
|
||||
--namespace cattle-system \
|
||||
--version <DEPLOYED_CHART_VERSION> \
|
||||
--set hostname=rancher.my.org \
|
||||
--set ...
|
||||
```
|
||||
|
||||
On upgrade, you can either
|
||||
|
||||
- remove `--set ingress.tls.source=secret \` from the Helm upgrade command, as shown above, or
|
||||
|
||||
- remove the `privateCA` parameter or set it to `false` because the CA is valid:
|
||||
|
||||
```
|
||||
set privateCA=false
|
||||
```
|
||||
|
||||
## 4. Reconfigure Rancher agents for the non-private/common certificate
|
||||
|
||||
`CATTLE_CA_CHECKSUM` environment variable on the downstream cluster agents should be removed or set to "" (an empty string).
|
||||
+181
@@ -0,0 +1,181 @@
|
||||
---
|
||||
title: Upgrading Cert-Manager with Helm 2
|
||||
weight: 2040
|
||||
aliases:
|
||||
- /rancher/v2.0-v2.4/en/installation/options/upgrading-cert-manager/helm-2-instructions
|
||||
- /rancher/v2.0-v2.4/en/installation/resources/choosing-version/encryption/upgrading-cert-manager/helm-2-instructions
|
||||
- /rancher/v2.x/en/installation/resources/upgrading-cert-manager/helm-2-instructions/
|
||||
---
|
||||
|
||||
Rancher uses cert-manager to automatically generate and renew TLS certificates for HA deployments of Rancher. As of Fall 2019, three important changes to cert-manager are set to occur that you need to take action on if you have an HA deployment of Rancher:
|
||||
|
||||
1. [Let's Encrypt will be blocking cert-manager instances older than 0.8.0 starting November 1st 2019.](https://community.letsencrypt.org/t/blocking-old-cert-manager-versions/98753)
|
||||
1. [Cert-manager is deprecating and replacing the certificate.spec.acme.solvers field](https://docs.cert-manager.io/en/latest/tasks/upgrading/upgrading-0.7-0.8.html#upgrading-from-v0-7-to-v0-8). This change has no exact deadline.
|
||||
1. [Cert-manager is deprecating `v1alpha1` API and replacing its API group](https://cert-manager.io/docs/installation/upgrading/upgrading-0.10-0.11/)
|
||||
|
||||
To address these changes, this guide will do two things:
|
||||
|
||||
1. Document the procedure for upgrading cert-manager
|
||||
1. Explain the cert-manager API changes and link to cert-manager's offficial documentation for migrating your data
|
||||
|
||||
> **Important:**
|
||||
> If you are currently running the cert-manager whose version is older than v0.11, and want to upgrade both Rancher and cert-manager to a newer version, you need to reinstall both of them:
|
||||
|
||||
> 1. Take a one-time snapshot of your Kubernetes cluster running Rancher server
|
||||
> 2. Uninstall Rancher, cert-manager, and the CustomResourceDefinition for cert-manager
|
||||
> 3. Install the newer version of Rancher and cert-manager
|
||||
|
||||
> The reason is that when Helm upgrades Rancher, it will reject the upgrade and show error messages if the running Rancher app does not match the chart template used to install it. Because cert-manager changed its API group and we cannot modify released charts for Rancher, there will always be a mismatch on the cert-manager's API version, therefore the upgrade will be rejected.
|
||||
|
||||
> For reinstalling Rancher with Helm, please check [Option B: Reinstalling Rancher Chart](installation/upgrades-rollbacks/upgrades/ha/) under the upgrade Rancher section.
|
||||
|
||||
## Upgrade Cert-Manager Only
|
||||
|
||||
> **Note:**
|
||||
> These instructions are applied if you have no plan to upgrade Rancher.
|
||||
|
||||
The namespace used in these instructions depends on the namespace cert-manager is currently installed in. If it is in kube-system use that in the instructions below. You can verify by running `kubectl get pods --all-namespaces` and checking which namespace the cert-manager-\* pods are listed in. Do not change the namespace cert-manager is running in or this can cause issues.
|
||||
|
||||
In order to upgrade cert-manager, follow these instructions:
|
||||
|
||||
<details id="normal">
|
||||
<summary>Upgrading cert-manager with Internet access</summary>
|
||||
1. Back up existing resources as a precaution
|
||||
|
||||
```plain
|
||||
kubectl get -o yaml --all-namespaces issuer,clusterissuer,certificates > cert-manager-backup.yaml
|
||||
```
|
||||
|
||||
1. Delete the existing deployment
|
||||
|
||||
```plain
|
||||
helm delete --purge cert-manager
|
||||
```
|
||||
|
||||
1. Install the CustomResourceDefinition resources separately
|
||||
|
||||
```plain
|
||||
kubectl apply -f https://raw.githubusercontent.com/jetstack/cert-manager/release-0.12/deploy/manifests/00-crds.yaml
|
||||
```
|
||||
|
||||
1. Add the Jetstack Helm repository
|
||||
|
||||
```plain
|
||||
helm repo add jetstack https://charts.jetstack.io
|
||||
```
|
||||
|
||||
1. Update your local Helm chart repository cache
|
||||
|
||||
```plain
|
||||
helm repo update
|
||||
```
|
||||
|
||||
1. Install the new version of cert-manager
|
||||
|
||||
```plain
|
||||
helm install --version 0.12.0 --name cert-manager --namespace kube-system jetstack/cert-manager
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
<details id="airgap">
|
||||
<summary>Upgrading cert-manager in an airgapped environment</summary>
|
||||
|
||||
### Prerequisites
|
||||
|
||||
Before you can perform the upgrade, you must prepare your air gapped environment by adding the necessary container images to your private registry and downloading or rendering the required Kubernetes manifest files.
|
||||
|
||||
1. Follow the guide to [Prepare your Private Registry](installation/air-gap-installation/prepare-private-reg/) with the images needed for the upgrade.
|
||||
|
||||
1. From a system connected to the internet, add the cert-manager repo to Helm
|
||||
|
||||
```plain
|
||||
helm repo add jetstack https://charts.jetstack.io
|
||||
helm repo update
|
||||
```
|
||||
|
||||
1. Fetch the latest cert-manager chart available from the [Helm chart repository](https://hub.helm.sh/charts/jetstack/cert-manager).
|
||||
|
||||
```plain
|
||||
helm fetch jetstack/cert-manager --version v0.12.0
|
||||
```
|
||||
|
||||
1. Render the cert manager template with the options you would like to use to install the chart. Remember to set the `image.repository` option to pull the image from your private registry. This will create a `cert-manager` directory with the Kubernetes manifest files.
|
||||
|
||||
```plain
|
||||
helm template ./cert-manager-v0.12.0.tgz --output-dir . \
|
||||
--name cert-manager --namespace kube-system \
|
||||
--set image.repository=<REGISTRY.YOURDOMAIN.COM:PORT>/quay.io/jetstack/cert-manager-controller
|
||||
--set webhook.image.repository=<REGISTRY.YOURDOMAIN.COM:PORT>/quay.io/jetstack/cert-manager-webhook
|
||||
--set cainjector.image.repository=<REGISTRY.YOURDOMAIN.COM:PORT>/quay.io/jetstack/cert-manager-cainjector
|
||||
```
|
||||
|
||||
1. Download the required CRD file for cert-manager
|
||||
|
||||
```plain
|
||||
curl -L -o cert-manager/cert-manager-crd.yaml https://raw.githubusercontent.com/jetstack/cert-manager/release-0.12/deploy/manifests/00-crds.yaml
|
||||
```
|
||||
|
||||
### Install cert-manager
|
||||
|
||||
1. Back up existing resources as a precaution
|
||||
|
||||
```plain
|
||||
kubectl get -o yaml --all-namespaces issuer,clusterissuer,certificates > cert-manager-backup.yaml
|
||||
```
|
||||
|
||||
1. Delete the existing cert-manager installation
|
||||
|
||||
```plain
|
||||
kubectl -n kube-system delete deployment,sa,clusterrole,clusterrolebinding -l 'app=cert-manager' -l 'chart=cert-manager-v0.5.2'
|
||||
```
|
||||
|
||||
1. Install the CustomResourceDefinition resources separately
|
||||
|
||||
```plain
|
||||
kubectl apply -f cert-manager/cert-manager-crd.yaml
|
||||
```
|
||||
|
||||
|
||||
1. Install cert-manager
|
||||
|
||||
```plain
|
||||
kubectl -n kube-system apply -R -f ./cert-manager
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
|
||||
Once you’ve installed cert-manager, you can verify it is deployed correctly by checking the kube-system namespace for running pods:
|
||||
|
||||
```
|
||||
kubectl get pods --namespace kube-system
|
||||
|
||||
NAME READY STATUS RESTARTS AGE
|
||||
cert-manager-7cbdc48784-rpgnt 1/1 Running 0 3m
|
||||
cert-manager-webhook-5b5dd6999-kst4x 1/1 Running 0 3m
|
||||
cert-manager-cainjector-3ba5cd2bcd-de332x 1/1 Running 0 3m
|
||||
```
|
||||
|
||||
If the ‘webhook’ pod (2nd line) is in a ContainerCreating state, it may still be waiting for the Secret to be mounted into the pod. Wait a couple of minutes for this to happen but if you experience problems, please check cert-manager's [troubleshooting](https://docs.cert-manager.io/en/latest/getting-started/troubleshooting.html) guide.
|
||||
|
||||
> **Note:** The above instructions ask you to add the disable-validation label to the kube-system namespace. Here are additional resources that explain why this is necessary:
|
||||
>
|
||||
> - [Information on the disable-validation label](https://docs.cert-manager.io/en/latest/tasks/upgrading/upgrading-0.4-0.5.html?highlight=certmanager.k8s.io%2Fdisable-validation#disabling-resource-validation-on-the-cert-manager-namespace)
|
||||
> - [Information on webhook validation for certificates](https://docs.cert-manager.io/en/latest/getting-started/webhook.html)
|
||||
|
||||
## Cert-Manager API change and data migration
|
||||
|
||||
Cert-manager has deprecated the use of the `certificate.spec.acme.solvers` field and will drop support for it completely in an upcoming release.
|
||||
|
||||
Per the cert-manager documentation, a new format for configuring ACME certificate resources was introduced in v0.8. Specifically, the challenge solver configuration field was moved. Both the old format and new are supported as of v0.9, but support for the old format will be dropped in an upcoming release of cert-manager. The cert-manager documentation strongly recommends that after upgrading you update your ACME Issuer and Certificate resources to the new format.
|
||||
|
||||
Details about the change and migration instructions can be found in the [cert-manager v0.7 to v0.8 upgrade instructions](https://cert-manager.io/docs/installation/upgrading/upgrading-0.7-0.8/).
|
||||
|
||||
The v0.11 release marks the removal of the v1alpha1 API that was used in previous versions of cert-manager, as well as our API group changing to be `cert-manager.io` instead of `certmanager.k8s.io.`
|
||||
|
||||
We have also removed support for the old configuration format that was deprecated in the v0.8 release. This means you must transition to using the new solvers style configuration format for your ACME issuers before upgrading to v0.11. For more information, see the [upgrading to v0.8 guide](https://cert-manager.io/docs/installation/upgrading/upgrading-0.7-0.8/).
|
||||
|
||||
Details about the change and migration instructions can be found in the [cert-manager v0.10 to v0.11 upgrade instructions](https://cert-manager.io/docs/installation/upgrading/upgrading-0.10-0.11/).
|
||||
|
||||
For information on upgrading from all other versions of cert-manager, refer to the [official documentation](https://cert-manager.io/docs/installation/upgrading/).
|
||||
+246
@@ -0,0 +1,246 @@
|
||||
---
|
||||
title: Upgrading Cert-Manager
|
||||
weight: 4
|
||||
aliases:
|
||||
- /rancher/v2.0-v2.4/en/installation/options/upgrading-cert-manager
|
||||
- /rancher/v2.0-v2.4/en/installation/options/upgrading-cert-manager/helm-2-instructions
|
||||
- /rancher/v2.0-v2.4/en/installation/resources/encryption/upgrading-cert-manager
|
||||
---
|
||||
|
||||
Rancher uses cert-manager to automatically generate and renew TLS certificates for HA deployments of Rancher. As of Fall 2019, three important changes to cert-manager are set to occur that you need to take action on if you have an HA deployment of Rancher:
|
||||
|
||||
1. [Let's Encrypt will be blocking cert-manager instances older than 0.8.0 starting November 1st 2019.](https://community.letsencrypt.org/t/blocking-old-cert-manager-versions/98753)
|
||||
1. [Cert-manager is deprecating and replacing the certificate.spec.acme.solvers field](https://cert-manager.io/docs/installation/upgrading/upgrading-0.7-0.8/). This change has no exact deadline.
|
||||
1. [Cert-manager is deprecating `v1alpha1` API and replacing its API group](https://cert-manager.io/docs/installation/upgrading/upgrading-0.10-0.11/)
|
||||
|
||||
To address these changes, this guide will do two things:
|
||||
|
||||
1. Document the procedure for upgrading cert-manager
|
||||
1. Explain the cert-manager API changes and link to cert-manager's official documentation for migrating your data
|
||||
|
||||
> **Important:**
|
||||
> If you are currently running the cert-manager whose version is older than v0.11, and want to upgrade both Rancher and cert-manager to a newer version, you need to reinstall both of them:
|
||||
|
||||
> 1. Take a one-time snapshot of your Kubernetes cluster running Rancher server
|
||||
> 2. Uninstall Rancher, cert-manager, and the CustomResourceDefinition for cert-manager
|
||||
> 3. Install the newer version of Rancher and cert-manager
|
||||
|
||||
> The reason is that when Helm upgrades Rancher, it will reject the upgrade and show error messages if the running Rancher app does not match the chart template used to install it. Because cert-manager changed its API group and we cannot modify released charts for Rancher, there will always be a mismatch on the cert-manager's API version, therefore the upgrade will be rejected.
|
||||
|
||||
> For reinstalling Rancher with Helm, please check [Option B: Reinstalling Rancher Chart](installation/upgrades-rollbacks/upgrades/ha/) under the upgrade Rancher section.
|
||||
|
||||
# Upgrade Cert-Manager
|
||||
|
||||
The namespace used in these instructions depends on the namespace cert-manager is currently installed in. If it is in kube-system use that in the instructions below. You can verify by running `kubectl get pods --all-namespaces` and checking which namespace the cert-manager-\* pods are listed in. Do not change the namespace cert-manager is running in or this can cause issues.
|
||||
|
||||
> These instructions have been updated for Helm 3. If you are still using Helm 2, refer to [these instructions.](installation/options/upgrading-cert-manager/helm-2-instructions)
|
||||
|
||||
In order to upgrade cert-manager, follow these instructions:
|
||||
|
||||
### Option A: Upgrade cert-manager with Internet Access
|
||||
|
||||
<details id="normal">
|
||||
<summary>Click to expand</summary>
|
||||
1. [Back up existing resources](https://cert-manager.io/docs/tutorials/backup/) as a precaution
|
||||
|
||||
```plain
|
||||
kubectl get -o yaml --all-namespaces \
|
||||
issuer,clusterissuer,certificates,certificaterequests > cert-manager-backup.yaml
|
||||
```
|
||||
|
||||
> **Important:**
|
||||
> If you are upgrading from a version older than 0.11.0, Update the apiVersion on all your backed up resources from `certmanager.k8s.io/v1alpha1` to `cert-manager.io/v1alpha2`. If you use any cert-manager annotations on any of your other resources, you will need to update them to reflect the new API group. For details, refer to the documentation on [additional annotation changes.](https://cert-manager.io/docs/installation/upgrading/upgrading-0.10-0.11/#additional-annotation-changes)
|
||||
|
||||
1. [Uninstall existing deployment](https://cert-manager.io/docs/installation/uninstall/kubernetes/#uninstalling-with-helm)
|
||||
|
||||
```plain
|
||||
helm uninstall cert-manager
|
||||
```
|
||||
|
||||
Delete the CustomResourceDefinition using the link to the version vX.Y.Z you installed
|
||||
|
||||
```plain
|
||||
kubectl delete -f https://github.com/jetstack/cert-manager/releases/download/vX.Y.Z/cert-manager.crds.yaml
|
||||
```
|
||||
|
||||
1. Install the CustomResourceDefinition resources separately
|
||||
|
||||
```plain
|
||||
kubectl apply --validate=false -f https://github.com/jetstack/cert-manager/releases/download/vX.Y.Z/cert-manager.crds.yaml
|
||||
```
|
||||
|
||||
> **Note:**
|
||||
> If you are running Kubernetes v1.15 or below, you will need to add the `--validate=false` flag to your `kubectl apply` command above. Otherwise, you will receive a validation error relating to the `x-kubernetes-preserve-unknown-fields` field in cert-manager’s CustomResourceDefinition resources. This is a benign error and occurs due to the way kubectl performs resource validation.
|
||||
|
||||
1. Create the namespace for cert-manager if needed
|
||||
|
||||
```plain
|
||||
kubectl create namespace cert-manager
|
||||
```
|
||||
|
||||
1. Add the Jetstack Helm repository
|
||||
|
||||
```plain
|
||||
helm repo add jetstack https://charts.jetstack.io
|
||||
```
|
||||
|
||||
1. Update your local Helm chart repository cache
|
||||
|
||||
```plain
|
||||
helm repo update
|
||||
```
|
||||
|
||||
1. Install the new version of cert-manager
|
||||
|
||||
```plain
|
||||
helm install \
|
||||
cert-manager jetstack/cert-manager \
|
||||
--namespace cert-manager \
|
||||
--version v0.12.0
|
||||
```
|
||||
|
||||
1. [Restore back up resources](https://cert-manager.io/docs/tutorials/backup/#restoring-resources)
|
||||
|
||||
```plain
|
||||
kubectl apply -f cert-manager-backup.yaml
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
### Option B: Upgrade cert-manager in an Air Gap Environment
|
||||
|
||||
<details id="airgap">
|
||||
<summary>Click to expand</summary>
|
||||
|
||||
### Prerequisites
|
||||
|
||||
Before you can perform the upgrade, you must prepare your air gapped environment by adding the necessary container images to your private registry and downloading or rendering the required Kubernetes manifest files.
|
||||
|
||||
1. Follow the guide to [Prepare your Private Registry](installation/air-gap-installation/prepare-private-reg/) with the images needed for the upgrade.
|
||||
|
||||
1. From a system connected to the internet, add the cert-manager repo to Helm
|
||||
|
||||
```plain
|
||||
helm repo add jetstack https://charts.jetstack.io
|
||||
helm repo update
|
||||
```
|
||||
|
||||
1. Fetch the latest cert-manager chart available from the [Helm chart repository](https://hub.helm.sh/charts/jetstack/cert-manager).
|
||||
|
||||
```plain
|
||||
helm fetch jetstack/cert-manager --version v0.12.0
|
||||
```
|
||||
|
||||
1. Render the cert manager template with the options you would like to use to install the chart. Remember to set the `image.repository` option to pull the image from your private registry. This will create a `cert-manager` directory with the Kubernetes manifest files.
|
||||
|
||||
The Helm 3 command is as follows:
|
||||
|
||||
```plain
|
||||
helm template cert-manager ./cert-manager-v0.12.0.tgz --output-dir . \
|
||||
--namespace cert-manager \
|
||||
--set image.repository=<REGISTRY.YOURDOMAIN.COM:PORT>/quay.io/jetstack/cert-manager-controller
|
||||
--set webhook.image.repository=<REGISTRY.YOURDOMAIN.COM:PORT>/quay.io/jetstack/cert-manager-webhook
|
||||
--set cainjector.image.repository=<REGISTRY.YOURDOMAIN.COM:PORT>/quay.io/jetstack/cert-manager-cainjector
|
||||
```
|
||||
|
||||
The Helm 2 command is as follows:
|
||||
|
||||
```plain
|
||||
helm template ./cert-manager-v0.12.0.tgz --output-dir . \
|
||||
--name cert-manager --namespace cert-manager \
|
||||
--set image.repository=<REGISTRY.YOURDOMAIN.COM:PORT>/quay.io/jetstack/cert-manager-controller
|
||||
--set webhook.image.repository=<REGISTRY.YOURDOMAIN.COM:PORT>/quay.io/jetstack/cert-manager-webhook
|
||||
--set cainjector.image.repository=<REGISTRY.YOURDOMAIN.COM:PORT>/quay.io/jetstack/cert-manager-cainjector
|
||||
```
|
||||
|
||||
1. Download the required CRD file for cert-manager (old and new)
|
||||
|
||||
```plain
|
||||
curl -L -o cert-manager/cert-manager-crd.yaml https://raw.githubusercontent.com/jetstack/cert-manager/release-0.12/deploy/manifests/00-crds.yaml
|
||||
curl -L -o cert-manager/cert-manager-crd-old.yaml https://raw.githubusercontent.com/jetstack/cert-manager/release-X.Y/deploy/manifests/00-crds.yaml
|
||||
```
|
||||
|
||||
### Install cert-manager
|
||||
|
||||
1. Back up existing resources as a precaution
|
||||
|
||||
```plain
|
||||
kubectl get -o yaml --all-namespaces \
|
||||
issuer,clusterissuer,certificates,certificaterequests > cert-manager-backup.yaml
|
||||
```
|
||||
|
||||
> **Important:**
|
||||
> If you are upgrading from a version older than 0.11.0, Update the apiVersion on all your backed up resources from `certmanager.k8s.io/v1alpha1` to `cert-manager.io/v1alpha2`. If you use any cert-manager annotations on any of your other resources, you will need to update them to reflect the new API group. For details, refer to the documentation on [additional annotation changes.](https://cert-manager.io/docs/installation/upgrading/upgrading-0.10-0.11/#additional-annotation-changes)
|
||||
|
||||
1. Delete the existing cert-manager installation
|
||||
|
||||
```plain
|
||||
kubectl -n cert-manager \
|
||||
delete deployment,sa,clusterrole,clusterrolebinding \
|
||||
-l 'app=cert-manager' -l 'chart=cert-manager-v0.5.2'
|
||||
```
|
||||
|
||||
Delete the CustomResourceDefinition using the link to the version vX.Y you installed
|
||||
|
||||
```plain
|
||||
kubectl delete -f cert-manager/cert-manager-crd-old.yaml
|
||||
```
|
||||
|
||||
1. Install the CustomResourceDefinition resources separately
|
||||
|
||||
```plain
|
||||
kubectl apply -f cert-manager/cert-manager-crd.yaml
|
||||
```
|
||||
|
||||
> **Note:**
|
||||
> If you are running Kubernetes v1.15 or below, you will need to add the `--validate=false` flag to your `kubectl apply` command above. Otherwise, you will receive a validation error relating to the `x-kubernetes-preserve-unknown-fields` field in cert-manager’s CustomResourceDefinition resources. This is a benign error and occurs due to the way kubectl performs resource validation.
|
||||
|
||||
1. Create the namespace for cert-manager
|
||||
|
||||
```plain
|
||||
kubectl create namespace cert-manager
|
||||
```
|
||||
|
||||
1. Install cert-manager
|
||||
|
||||
```plain
|
||||
kubectl -n cert-manager apply -R -f ./cert-manager
|
||||
```
|
||||
|
||||
1. [Restore back up resources](https://cert-manager.io/docs/tutorials/backup/#restoring-resources)
|
||||
|
||||
```plain
|
||||
kubectl apply -f cert-manager-backup.yaml
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
### Verify the Deployment
|
||||
|
||||
Once you’ve installed cert-manager, you can verify it is deployed correctly by checking the kube-system namespace for running pods:
|
||||
|
||||
```
|
||||
kubectl get pods --namespace cert-manager
|
||||
|
||||
NAME READY STATUS RESTARTS AGE
|
||||
cert-manager-5c6866597-zw7kh 1/1 Running 0 2m
|
||||
cert-manager-cainjector-577f6d9fd7-tr77l 1/1 Running 0 2m
|
||||
cert-manager-webhook-787858fcdb-nlzsq 1/1 Running 0 2m
|
||||
```
|
||||
|
||||
## Cert-Manager API change and data migration
|
||||
|
||||
Cert-manager has deprecated the use of the `certificate.spec.acme.solvers` field and will drop support for it completely in an upcoming release.
|
||||
|
||||
Per the cert-manager documentation, a new format for configuring ACME certificate resources was introduced in v0.8. Specifically, the challenge solver configuration field was moved. Both the old format and new are supported as of v0.9, but support for the old format will be dropped in an upcoming release of cert-manager. The cert-manager documentation strongly recommends that after upgrading you update your ACME Issuer and Certificate resources to the new format.
|
||||
|
||||
Details about the change and migration instructions can be found in the [cert-manager v0.7 to v0.8 upgrade instructions](https://cert-manager.io/docs/installation/upgrading/upgrading-0.7-0.8/).
|
||||
|
||||
The v0.11 release marks the removal of the v1alpha1 API that was used in previous versions of cert-manager, as well as our API group changing to be cert-manager.io instead of certmanager.k8s.io.
|
||||
|
||||
We have also removed support for the old configuration format that was deprecated in the v0.8 release. This means you must transition to using the new solvers style configuration format for your ACME issuers before upgrading to v0.11. For more information, see the [upgrading to v0.8 guide](https://cert-manager.io/docs/installation/upgrading/upgrading-0.7-0.8/).
|
||||
|
||||
Details about the change and migration instructions can be found in the [cert-manager v0.10 to v0.11 upgrade instructions](https://cert-manager.io/docs/installation/upgrading/upgrading-0.10-0.11/).
|
||||
|
||||
More info about [cert-manager upgrade information](https://cert-manager.io/docs/installation/upgrading/).
|
||||
|
||||
Reference in New Issue
Block a user