mirror of
https://github.com/rancher/rancher-docs.git
synced 2026-09-26 04:58:07 +00:00
Sync content from rancher/docs
Start: cb708da8d Jul 7 2022 End: 09d646cfc Sep 2 2022
This commit is contained in:
Billy Tat
+97
@@ -0,0 +1,97 @@
|
||||
---
|
||||
title: Prerequisites
|
||||
weight: 1
|
||||
---
|
||||
|
||||
### 1. Setting Up License Manager and Purchasing Support
|
||||
|
||||
First, complete the [first step](https://docs.aws.amazon.com/license-manager/latest/userguide/getting-started.html) of the license manager one-time setup.
|
||||
Next, go to the AWS Marketplace. Locate the "Rancher Premium Support Billing Container Starter Pack". Purchase at least one entitlement.
|
||||
|
||||
If you have installed Rancher using the "Rancher Setup" AWS Marketplace offering, skip to [Step 4](#4-create-an-oidc-provider).
|
||||
|
||||
> **Note:** Each entitlement grants access to support for a certain amount of nodes. You can purchase more licenses as necessary later on.
|
||||
|
||||
### 2. Create an EKS Cluster
|
||||
Follow the [Rancher docs](../../install-upgrade-on-a-kubernetes-cluster/rancher-on-amazon-eks.md) to create an EKS cluster. When you get to the [final step to install Rancher](../../install-upgrade-on-a-kubernetes-cluster/rancher-on-amazon-eks.md#8-install-the-rancher-helm-chart), **stop and return to this page**. This cluster will need to meet the following requirements:
|
||||
|
||||
- EKS version 1.22.
|
||||
- Each node in the cluster has access to the registry containing Rancher and its related images.
|
||||
- Each node in the cluster has access to the ECR repo storing the CSP Adapter.
|
||||
- Each node in the cluster has access to the license manager service.
|
||||
- Each node in the cluster has access to global endpoints for the STS service.
|
||||
|
||||
### 3. Install Rancher
|
||||
|
||||
In addition to the options specified to install Rancher in the [Rancher docs]({{<baseurl>}}/rancher/v2.6/en/installation/resources/k8s-tutorials/amazon-eks/#8-install-the-rancher-helm-chart), you will also need to enable extra metrics.
|
||||
This can be done through the Helm CLI through the following options:
|
||||
|
||||
```bash
|
||||
--set extraEnv\[0\].name="CATTLE_PROMETHEUS_METRICS" --set-string extraEnv\[0\].value=true
|
||||
```
|
||||
|
||||
You can also use a values.yaml like the below:
|
||||
|
||||
```yaml
|
||||
extraEnv:
|
||||
- name: "CATTLE_PROMETHEUS_METRICS"
|
||||
value: "true"
|
||||
```
|
||||
|
||||
You will also need to install Rancher version 2.6.7 or higher.
|
||||
|
||||
### 4. Create an OIDC Provider
|
||||
|
||||
Follow the [AWS documentation](https://docs.aws.amazon.com/eks/latest/userguide/enable-iam-roles-for-service-accounts.html) to create an OIDC provider for the cluster specified in the previous section.
|
||||
|
||||
### 5. Create an IAM Role
|
||||
|
||||
An IAM role is required for the CSP adapter to check-in/check-out entitlements.
|
||||
|
||||
First, configure the trust policy as below. Replace `MY_AWS_ACC` with your AWS account number, `MY_AWS_REGION` with your AWS region, and `MY_OIDC_PROVIDER` with the id of your OIDC provider:
|
||||
|
||||
```json
|
||||
{
|
||||
"Version": "2012-10-17",
|
||||
"Statement": [
|
||||
{
|
||||
"Effect": "Allow",
|
||||
"Principal": {
|
||||
"Federated": "arn:aws:iam::${MY_AWS_ACC}:oidc-provider/oidc.eks.${MY_AWS_REGION}.amazonaws.com/id/${MY_OIDC_PROVIDER}"
|
||||
},
|
||||
"Action": "sts:AssumeRoleWithWebIdentity",
|
||||
"Condition": {
|
||||
"StringEquals": {
|
||||
"oidc.eks.${MY_AWS_REGION}.amazonaws.com/id/${MY_OIDC_PROVIDER}:sub": "system:serviceaccount:cattle-csp-adapter-system:rancher-csp-adapter",
|
||||
"oidc.eks.${MY_AWS_REGION}.amazonaws.com/id/${MY_OIDC_PROVIDER}:aud": "sts.amazonaws.com"
|
||||
}
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Next, use a policy for the role which has the following permissions:
|
||||
|
||||
```json
|
||||
{
|
||||
"Version": "2012-10-17",
|
||||
"Statement": [
|
||||
{
|
||||
"Sid": "RancherCSPAdapterPermissions",
|
||||
"Effect": "Allow",
|
||||
"Action": [
|
||||
"license-manager:ListReceivedLicenses",
|
||||
"license-manager:CheckoutLicense",
|
||||
"license-manager:ExtendLicenseConsumption",
|
||||
"license-manager:CheckInLicense",
|
||||
"license-manager:GetLicense",
|
||||
"license-manager:GetLicenseUsage"
|
||||
],
|
||||
"Resource": "*"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Save the name of the role. You will need it later on when installing the CSP adapter.
|
||||
+29
@@ -0,0 +1,29 @@
|
||||
---
|
||||
title: Common Issues
|
||||
weight: 4
|
||||
---
|
||||
|
||||
**After installing the adapter, a banner message appears in Rancher that says "AWS Marketplace Adapter: Unable to run the adapter, please check the adapter logs"**
|
||||
|
||||
This error indicates that while the adapter was installed into the cluster, an error has occurred which prevents it from properly checking-in/checking-out licenses.
|
||||
|
||||
This often occurs because the IAM role was not set up properly. Review the [prerequisites](./adapter-requirements.md) and verify that:
|
||||
|
||||
- An OIDC provider has been created/associated with the cluster Rancher is running on.
|
||||
- The IAM role has been configured to trust this OIDC provider.
|
||||
- The IAM role has at least the permissions outlined in the policy.
|
||||
|
||||
If all of the above have been configured correctly, reach out to support for assistance.
|
||||
|
||||
**I see a banner message that states, "AWS Marketplace Adapter: You have exceeded your licensed node count. At least x more license(s) are required in AWS to become compliant"**
|
||||
|
||||
This message indicates that you do not have enough entitlements for the amount of nodes Rancher is currently managing.
|
||||
|
||||
Keep in mind the following limitations:
|
||||
|
||||
- Each entitlement is valid for a certain number of nodes.
|
||||
- Every node currently managed by Rancher counts toward your usage total (with exception of nodes in the cluster rancher is installed on).
|
||||
- Each entitlement can be used by at most one Rancher instance. For example, if you have two running Rancher instances in your account (each installed on a separate EKS cluster), then you will need at least two entitlements.
|
||||
|
||||
You may also have recently uninstalled/re-installed the adapter. If the adapter loses track of the licenses that it is currently managing, it can take up to an hour to resolve the actual state of the licenses.
|
||||
|
||||
+141
@@ -0,0 +1,141 @@
|
||||
---
|
||||
title: Installing the Adapter
|
||||
weight: 2
|
||||
---
|
||||
|
||||
> **Important:** If you are attempting to re-install the adapter, you may experience errant out-of-compliance messages for up to an hour.
|
||||
|
||||
### 1. Gain Access to the Local Cluster
|
||||
|
||||
> **Note:** Only admin users should have access to the local cluster. Because the CSP adapter must be installed in the local cluster, this installation must be carried out by an admin user.
|
||||
|
||||
First, click on the local cluster and download a kubeconfig token. You can then configure your CLI to use this new token with the following command, replacing `$TOKEN_PATH` with the path on your filesystem to the downloaded token:
|
||||
|
||||
```bash
|
||||
export KUBECONFIG=$TOKEN_PATH
|
||||
```
|
||||
|
||||
### 2. Create the Adapter Namespace
|
||||
|
||||
Create the namespace that the adapter will be installed in.
|
||||
|
||||
```bash
|
||||
kubectl create ns cattle-csp-adapter-system
|
||||
```
|
||||
|
||||
### 3. Create Certificate Secrets
|
||||
|
||||
The adapter requires access to the root CA that Rancher is using to communicate with the Rancher server. You can read more about which certificate options Rancher supports in the [chart options page](../../../../reference-guides/installation-references/helm-chart-options.md).
|
||||
|
||||
If your Rancher install uses a certificate signed by a recognized Certificate Authority such as Let's Encrypt, then you can safely skip to [Step 4](#4-install-the-chart).
|
||||
|
||||
However, if your Rancher install uses a custom certificate such as a Rancher-generated certificate or one signed by a private Certificate Authority, you will need to provide the certificate for this authority in PEM-encoded format so that the adapter can communicate with Rancher.
|
||||
|
||||
First, retrieve the certificate that Rancher is using and place in a file named `ca-additional.pem`. If you are using the Rancher-generated certs option, this can be done with the following command:
|
||||
|
||||
```bash
|
||||
kubectl get secret tls-rancher -n cattle-system -o jsonpath="{.data.tls\.crt}" | base64 -d >> ca-additional.pem
|
||||
```
|
||||
|
||||
Then, create a secret which uses this cert:
|
||||
|
||||
```bash
|
||||
kubectl -n cattle-csp-adapter-system create secret generic tls-ca-additional --from-file=ca-additional.pem
|
||||
```
|
||||
|
||||
> **Important:** Do not change the names of the file or of the created secret. Making changes to these values may result in errors when the adapter runs.
|
||||
|
||||
### 4. Install the Chart
|
||||
|
||||
First, add the `rancher/charts` repo using the following command:
|
||||
|
||||
```bash
|
||||
helm repo add rancher-charts https://charts.rancher.io
|
||||
```
|
||||
|
||||
Next, install the CSP adapter. You must specify several values, including the account number, and the name of the role created in the prerequisites.
|
||||
|
||||
For the below instructions, replace `$MY_ACC_NUM` with your AWS account number and `$MY_ROLE_NAME` with the name of the role created in the prerequisites.
|
||||
|
||||
> **Note:** If you use shell variables, do not specify quotation marks. For example, MY_ACC_NUM=123456789012 will work, but MY_ACC_NUM="123456789012" will fail.
|
||||
|
||||
> **Note:** Accounts using the AWS Marketplace listing for the EU and the UK will need to specify an additional `--set image.repository=rancher/rancher-csp-adapter-eu` option. To see if your account needs this option when installing the adapter, refer to the usage instructions of the marketplace listing.
|
||||
|
||||
> **Note:** It is important that you follow the instructions below exactly. In particular, the command to install version 1.0.1 of the adapter (by using --set image.tag=v1.0.1) is key to ensure that node counts are accurate.
|
||||
|
||||
{{% tabs %}}
|
||||
{{% tab "Let's Encrypt/ Public Certificate Authority" %}}
|
||||
|
||||
```bash
|
||||
helm install rancher-csp-adapter rancher-charts/rancher-csp-adapter --namespace cattle-csp-adapter-system --set aws.enabled=true --set aws.roleName=$MY_ROLE_NAME --set-string aws.accountNumber=$MY_ACC_NUM --set image.tag=v1.0.1
|
||||
```
|
||||
|
||||
|
||||
Alternatively, you can use a `values.yaml` and specify options like below:
|
||||
|
||||
```yaml
|
||||
image:
|
||||
tag: v1.0.1
|
||||
aws:
|
||||
enabled: true
|
||||
accountNumber: "$MY_ACC_NUM"
|
||||
roleName: $MY_ROLE_NAME
|
||||
```
|
||||
|
||||
> **Note:** The account number needs to be specified in a string format, like the above, or the installation will fail.
|
||||
|
||||
You can then install the adapter with the following command:
|
||||
|
||||
```bash
|
||||
helm install rancher-csp-adapter rancher-charts/rancher-csp-adapter -f values.yaml
|
||||
```
|
||||
|
||||
{{% /tab %}}
|
||||
{{% tab "Private CA Authority / Rancher-generated Certificates" %}}
|
||||
|
||||
```bash
|
||||
helm install rancher-csp-adapter rancher-charts/rancher-csp-adapter --namespace cattle-csp-adapter-system --set aws.enabled=true --set aws.roleName=$MY_ROLE_NAME --set-string aws.accountNumber=$MY_ACC_NUM --set additionalTrustedCAs=true --set image.tag=v1.0.1
|
||||
```
|
||||
|
||||
Alternatively, you can use a `values.yaml` and specify options the below:
|
||||
|
||||
```yaml
|
||||
image:
|
||||
tag: v1.0.1
|
||||
aws:
|
||||
enabled: true
|
||||
accountNumber: "$MY_ACC_NUM"
|
||||
roleName: $MY_ROLE_NAME
|
||||
additionalTrustedCAs: true
|
||||
```
|
||||
|
||||
> **Note:** The account number needs to be specified in a string format, like the above, or the installation will fail.
|
||||
|
||||
You can then install the adapter with the following command:
|
||||
|
||||
```bash
|
||||
helm install rancher-csp-adapter rancher-charts/rancher-csp-adapter -f values.yaml
|
||||
```
|
||||
|
||||
{{% /tab %}}
|
||||
{{% /tabs %}}
|
||||
|
||||
### 5. Managing Certificate Updates
|
||||
|
||||
If you had to create a secret storing a custom cert in [Step 3](#3-create-certificate-secrets), you will need to update this secret over time as the certificate is rotated.
|
||||
|
||||
First, delete the original secret in the cattle-csp-adapter-system namespace, using the below command:
|
||||
|
||||
```bash
|
||||
kubectl delete secret tls-ca-additional -n cattle-csp-adapter-system
|
||||
```
|
||||
|
||||
Then, follow the original installation steps in [Step 3](#3-create-certificate-secrets) to replace the content of the secret with the updated value.
|
||||
|
||||
Finally, restart the rancher-csp-adapter deployment to ensure that the updated value is made available to the adapter:
|
||||
|
||||
```bash
|
||||
kubectl rollout restart deploy rancher-csp-adapter -n cattle-csp-adapter-system
|
||||
```
|
||||
|
||||
> **Note:** There are methods such as cert-manager's [trust operator](https://cert-manager.io/docs/projects/trust/) which can help reduce the number of manual rotation tasks over time. While these options are not officially supported, they may be useful to users wishing to automate some of these tasks.
|
||||
+22
@@ -0,0 +1,22 @@
|
||||
---
|
||||
title: Uninstalling The Adapter
|
||||
weight: 3
|
||||
---
|
||||
|
||||
### 1. Uninstall the adapter chart using helm.
|
||||
|
||||
```bash
|
||||
helm uninstall rancher-csp-adapter -n cattle-csp-adapter-system
|
||||
```
|
||||
|
||||
### 2. Remove the namespace created for the adapter.
|
||||
|
||||
```bash
|
||||
kubectl delete ns cattle-csp-adapter-system
|
||||
```
|
||||
|
||||
### 3. (Optional) remove any outstanding user notifications.
|
||||
|
||||
```bash
|
||||
kubectl delete RancherUserNotification csp-compliance
|
||||
```
|
||||
@@ -0,0 +1,54 @@
|
||||
---
|
||||
title: Supportconfig bundle
|
||||
weight: 100
|
||||
---
|
||||
|
||||
After installing the CSP adapter, you will have the ability to generate a supportconfig bundle. This bundle is a tar file which can be used to quickly provide information to support.
|
||||
|
||||
These bundles can be created through Rancher or through direct access to the cluster that Rancher is installed on. Note that accessing through Rancher is preferred.
|
||||
|
||||
> **Note:** Only admin users can generate/download supportconfig bundles, regardless of method.
|
||||
|
||||
### Accessing through Rancher
|
||||
|
||||
First, click on the hamburger menu. Then click the `Get Support` button.
|
||||
|
||||
|
||||
|
||||
In the next page, click on the `Generate Support Config` button.
|
||||
|
||||
> **Note:** If the adapter is not installed, the option to generate the supportconfig bundle will not be present. You must install the CSP adapter to generate a supportconfig bundle.
|
||||
|
||||
|
||||
|
||||
### Accessing without rancher
|
||||
|
||||
First, generate a kubeconfig for the cluster that Rancher is installed on.
|
||||
|
||||
> **Note:** If Rancher is down, you will not be able to use a kubeconfig token generated by Rancher to access the cluster.
|
||||
|
||||
Configure your shell environment to use this kubeconfig token:
|
||||
|
||||
```bash
|
||||
export KUBECONFIG=$MY_KUBECONFIG_PATH
|
||||
```
|
||||
|
||||
It is recommended to create a temporary working directory while running this command, like below:
|
||||
|
||||
```bash
|
||||
mkdir temp && cd temp
|
||||
```
|
||||
|
||||
Then, retrieve the supportconfig bundle:
|
||||
|
||||
```bash
|
||||
mkdir rancher && kubectl get configmap csp-config -n cattle-csp-adapter-system -o=jsonpath='{.data.data}' >> rancher/config.json && tar -c -f supportconfig_rancher.tar rancher && rm -rf rancher
|
||||
```
|
||||
|
||||
This will create a `supportconfig_rancher.tar` file in your current directory.
|
||||
|
||||
Users who run these commands on Mac may experience issues due to incompatibilities between gnu-tar and bsd-tar. If support has issues reading a supportconfig that you produce, try using the below command after making gnu-tar accessible as `gtar` on your path:
|
||||
|
||||
```bash
|
||||
mkdir rancher && kubectl get configmap csp-config -n cattle-csp-adapter-system -o=jsonpath='{.data.data}' >> rancher/config.json && gtar -c -f supportconfig_rancher.tar rancher && rm -rf rancher
|
||||
```
|
||||
@@ -100,6 +100,89 @@ Below are the minimum recommended computing resources for the NeuVector chart in
|
||||
\* Minimum 1GB of memory total required for Controller, Manager, and Scanner containers combined.
|
||||
|
||||
|
||||
### Hardened Cluster Support - Calico and Canal
|
||||
|
||||
{{% tabs %}}
|
||||
{{% tab "RKE1" %}}
|
||||
|
||||
- All NeuVector components are deployable if PSP is set to true.
|
||||
|
||||
**_New in v2.6.7_**
|
||||
|
||||
You will need to set additional configuration for your hardened cluster environment as follows:
|
||||
|
||||
1. Click **☰ > Cluster Management**.
|
||||
1. Go to the cluster that you created and click **Explore**.
|
||||
1. In the left navigation bar, click **Apps & Marketplace**.
|
||||
1. Install (or upgrade to) NeuVector version `100.0.1+up2.2.2`.
|
||||
|
||||
- Under **Edit Options** > **Other Configuration**, enable **Pod Security Policy** by checking the box (no other config needed):
|
||||
|
||||
|
||||
|
||||
1. Click **Install** at the bottom-right to complete.
|
||||
|
||||
|
||||
{{% /tab %}}
|
||||
{{% tab "RKE2" %}}
|
||||
|
||||
- NeuVector components Controller and Enforcer are deployable if PSP is set to true.
|
||||
|
||||
|
||||
**Applicable to NeuVector chart version 100.0.0+up2.2.0 only:**
|
||||
|
||||
- For Manager, Scanner, and Updater components, additional configuration is required as shown below:
|
||||
|
||||
```
|
||||
kubectl patch deploy neuvector-manager-pod -n cattle-neuvector-system --patch '{"spec":{"template":{"spec":{"securityContext":{"runAsUser": 5400}}}}}'
|
||||
kubectl patch deploy neuvector-scanner-pod -n cattle-neuvector-system --patch '{"spec":{"template":{"spec":{"securityContext":{"runAsUser": 5400}}}}}'
|
||||
kubectl patch cronjob neuvector-updater-pod -n cattle-neuvector-system --patch '{"spec":{"jobTemplate":{"spec":{"template":{"spec":{"securityContext":{"runAsUser": 5400}}}}}}}'
|
||||
```
|
||||
<br/>
|
||||
|
||||
**_New in v2.6.7_**
|
||||
|
||||
You will need to set additional configuration for your hardened cluster environment.
|
||||
|
||||
>**Note:** You must update your config in both RKE2 and K3s hardened clusters as shown below.
|
||||
|
||||
1. Click **☰ > Cluster Management**.
|
||||
1. Go to the cluster that you created and click **Explore**.
|
||||
1. In the left navigation bar, click **Apps & Marketplace**.
|
||||
1. Install (or upgrade to) NeuVector version `100.0.1+up2.2.2`.
|
||||
|
||||
- Under **Edit Options** > **Other Configuration**, enable **Pod Security Policy** by checking the box. Note that you must also enter a value greater than `zero` for `Manager runAsUser ID`, `Scanner runAsUser ID`, and `Updater runAsUser ID`:
|
||||
|
||||
|
||||
|
||||
1. Click **Install** at the bottom-right to complete.
|
||||
|
||||
{{% /tab %}}
|
||||
{{% /tabs %}}
|
||||
|
||||
|
||||
### SELinux-enabled Cluster Support - Calico and Canal
|
||||
|
||||
To enable SELinux on RKE2 clusters, follow the steps below:
|
||||
|
||||
- NeuVector components Controller and Enforcer are deployable if PSP is set to true.
|
||||
|
||||
|
||||
**Applicable to NeuVector chart version 100.0.0+up2.2.0 only:**
|
||||
|
||||
- For Manager, Scanner, and Updater components, additional configuration is required as shown below:
|
||||
|
||||
```
|
||||
kubectl patch deploy neuvector-manager-pod -n cattle-neuvector-system --patch '{"spec":{"template":{"spec":{"securityContext":{"runAsUser": 5400}}}}}'
|
||||
kubectl patch deploy neuvector-scanner-pod -n cattle-neuvector-system --patch '{"spec":{"template":{"spec":{"securityContext":{"runAsUser": 5400}}}}}'
|
||||
kubectl patch cronjob neuvector-updater-pod -n cattle-neuvector-system --patch '{"spec":{"jobTemplate":{"spec":{"template":{"spec":{"securityContext":{"runAsUser": 5400}}}}}}}'
|
||||
```
|
||||
|
||||
### Cluster Support in an Air-Gapped Environment
|
||||
|
||||
- All NeuVector components are deployable on a cluster in an air-gapped environment without any additional configuration needed.
|
||||
|
||||
|
||||
### Support Limitations
|
||||
|
||||
* Only admins and cluster owners are currently supported.
|
||||
@@ -108,11 +191,6 @@ Below are the minimum recommended computing resources for the NeuVector chart in
|
||||
|
||||
* NeuVector is not supported on a Windows cluster.
|
||||
|
||||
* NeuVector installation is not supported on hardened clusters.
|
||||
|
||||
* NeuVector installation is not supported on SELinux clusters.
|
||||
|
||||
* NeuVector installation is not supported on clusters in an air-gapped environment.
|
||||
|
||||
### Other Limitations
|
||||
|
||||
|
||||
Reference in New Issue
Block a user