mirror of
https://github.com/rancher/rancher-docs.git
synced 2026-11-09 10:19:16 +00:00
1 line
14 KiB
JavaScript
1 line
14 KiB
JavaScript
"use strict";(self.webpackChunkrancher_docs=self.webpackChunkrancher_docs||[]).push([[49233],{3905:(e,t,a)=>{a.d(t,{Zo:()=>p,kt:()=>h});var r=a(67294);function n(e,t,a){return t in e?Object.defineProperty(e,t,{value:a,enumerable:!0,configurable:!0,writable:!0}):e[t]=a,e}function l(e,t){var a=Object.keys(e);if(Object.getOwnPropertySymbols){var r=Object.getOwnPropertySymbols(e);t&&(r=r.filter((function(t){return Object.getOwnPropertyDescriptor(e,t).enumerable}))),a.push.apply(a,r)}return a}function o(e){for(var t=1;t<arguments.length;t++){var a=null!=arguments[t]?arguments[t]:{};t%2?l(Object(a),!0).forEach((function(t){n(e,t,a[t])})):Object.getOwnPropertyDescriptors?Object.defineProperties(e,Object.getOwnPropertyDescriptors(a)):l(Object(a)).forEach((function(t){Object.defineProperty(e,t,Object.getOwnPropertyDescriptor(a,t))}))}return e}function i(e,t){if(null==e)return{};var a,r,n=function(e,t){if(null==e)return{};var a,r,n={},l=Object.keys(e);for(r=0;r<l.length;r++)a=l[r],t.indexOf(a)>=0||(n[a]=e[a]);return n}(e,t);if(Object.getOwnPropertySymbols){var l=Object.getOwnPropertySymbols(e);for(r=0;r<l.length;r++)a=l[r],t.indexOf(a)>=0||Object.prototype.propertyIsEnumerable.call(e,a)&&(n[a]=e[a])}return n}var c=r.createContext({}),s=function(e){var t=r.useContext(c),a=t;return e&&(a="function"==typeof e?e(t):o(o({},t),e)),a},p=function(e){var t=s(e.components);return r.createElement(c.Provider,{value:t},e.children)},u={inlineCode:"code",wrapper:function(e){var t=e.children;return r.createElement(r.Fragment,{},t)}},d=r.forwardRef((function(e,t){var a=e.components,n=e.mdxType,l=e.originalType,c=e.parentName,p=i(e,["components","mdxType","originalType","parentName"]),d=s(a),h=n,m=d["".concat(c,".").concat(h)]||d[h]||u[h]||l;return a?r.createElement(m,o(o({ref:t},p),{},{components:a})):r.createElement(m,o({ref:t},p))}));function h(e,t){var a=arguments,n=t&&t.mdxType;if("string"==typeof e||n){var l=a.length,o=new Array(l);o[0]=d;var i={};for(var c in t)hasOwnProperty.call(t,c)&&(i[c]=t[c]);i.originalType=e,i.mdxType="string"==typeof e?e:n,o[1]=i;for(var s=2;s<l;s++)o[s]=a[s];return r.createElement.apply(null,o)}return r.createElement.apply(null,a)}d.displayName="MDXCreateElement"},79933:(e,t,a)=>{a.r(t),a.d(t,{assets:()=>c,contentTitle:()=>o,default:()=>m,frontMatter:()=>l,metadata:()=>i,toc:()=>s});var r=a(87462),n=(a(67294),a(3905));const l={title:"Installing the Adapter"},o=void 0,i={unversionedId:"integrations-in-rancher/cloud-marketplace/aws-cloud-marketplace/install-adapter",id:"integrations-in-rancher/cloud-marketplace/aws-cloud-marketplace/install-adapter",title:"Installing the Adapter",description:"Important: If you are attempting to re-install the adapter, you may experience errant out-of-compliance messages for up to an hour.",source:"@site/docs/integrations-in-rancher/cloud-marketplace/aws-cloud-marketplace/install-adapter.md",sourceDirName:"integrations-in-rancher/cloud-marketplace/aws-cloud-marketplace",slug:"/integrations-in-rancher/cloud-marketplace/aws-cloud-marketplace/install-adapter",permalink:"/integrations-in-rancher/cloud-marketplace/aws-cloud-marketplace/install-adapter",draft:!1,editUrl:"https://github.com/rancher/rancher-docs/edit/main/docs/integrations-in-rancher/cloud-marketplace/aws-cloud-marketplace/install-adapter.md",tags:[],version:"current",lastUpdatedAt:1670452794,formattedLastUpdatedAt:"Dec 7, 2022",frontMatter:{title:"Installing the Adapter"},sidebar:"tutorialSidebar",previous:{title:"Prerequisites",permalink:"/integrations-in-rancher/cloud-marketplace/aws-cloud-marketplace/adapter-requirements"},next:{title:"Uninstalling The Adapter",permalink:"/integrations-in-rancher/cloud-marketplace/aws-cloud-marketplace/uninstall-adapter"}},c={},s=[{value:"Rancher vs. Adapter Compatibility Matrix",id:"rancher-vs-adapter-compatibility-matrix",level:3},{value:"1. Gain Access to the Local Cluster",id:"1-gain-access-to-the-local-cluster",level:3},{value:"2. Create the Adapter Namespace",id:"2-create-the-adapter-namespace",level:3},{value:"3. Create Certificate Secrets",id:"3-create-certificate-secrets",level:3},{value:"4. Install the Chart",id:"4-install-the-chart",level:3},{value:"5. Managing Certificate Updates",id:"5-managing-certificate-updates",level:3}],p=e=>function(t){return console.warn("Component "+e+" was not imported, exported, or provided by MDXProvider as global scope"),(0,n.kt)("div",t)},u=p("Tabs"),d=p("TabItem"),h={toc:s};function m(e){let{components:t,...a}=e;return(0,n.kt)("wrapper",(0,r.Z)({},h,a,{components:t,mdxType:"MDXLayout"}),(0,n.kt)("blockquote",null,(0,n.kt)("p",{parentName:"blockquote"},(0,n.kt)("strong",{parentName:"p"},"Important:")," If you are attempting to re-install the adapter, you may experience errant out-of-compliance messages for up to an hour.")),(0,n.kt)("h3",{id:"rancher-vs-adapter-compatibility-matrix"},"Rancher vs. Adapter Compatibility Matrix"),(0,n.kt)("admonition",{title:"Important:",type:"note"},(0,n.kt)("p",{parentName:"admonition"},"Different versions of the CSP adapter rely on features found in specific versions of Rancher.\nIn order to deploy and run the adapter successfully, you need to ensure its version corresponds to the necessary version of Rancher.")),(0,n.kt)("table",null,(0,n.kt)("thead",{parentName:"table"},(0,n.kt)("tr",{parentName:"thead"},(0,n.kt)("th",{parentName:"tr",align:null},"Rancher Version"),(0,n.kt)("th",{parentName:"tr",align:"center"},"Adapter Version"))),(0,n.kt)("tbody",{parentName:"table"},(0,n.kt)("tr",{parentName:"tbody"},(0,n.kt)("td",{parentName:"tr",align:null},"v2.7.0"),(0,n.kt)("td",{parentName:"tr",align:"center"},"v2.0.0")))),(0,n.kt)("h3",{id:"1-gain-access-to-the-local-cluster"},"1. Gain Access to the Local Cluster"),(0,n.kt)("blockquote",null,(0,n.kt)("p",{parentName:"blockquote"},(0,n.kt)("strong",{parentName:"p"},"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.")),(0,n.kt)("p",null,"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 ",(0,n.kt)("inlineCode",{parentName:"p"},"$TOKEN_PATH")," with the path on your filesystem to the downloaded token:"),(0,n.kt)("pre",null,(0,n.kt)("code",{parentName:"pre",className:"language-bash"},"export KUBECONFIG=$TOKEN_PATH\n")),(0,n.kt)("h3",{id:"2-create-the-adapter-namespace"},"2. Create the Adapter Namespace"),(0,n.kt)("p",null,"Create the namespace that the adapter will be installed in."),(0,n.kt)("pre",null,(0,n.kt)("code",{parentName:"pre",className:"language-bash"},"kubectl create ns cattle-csp-adapter-system\n")),(0,n.kt)("h3",{id:"3-create-certificate-secrets"},"3. Create Certificate Secrets"),(0,n.kt)("p",null,"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 ",(0,n.kt)("a",{parentName:"p",href:"/getting-started/installation-and-upgrade/installation-references/helm-chart-options"},"chart options page"),"."),(0,n.kt)("p",null,"If your Rancher install uses a certificate signed by a recognized Certificate Authority such as Let's Encrypt, then you can safely skip to ",(0,n.kt)("a",{parentName:"p",href:"#4-install-the-chart"},"Step 4"),"."),(0,n.kt)("p",null,"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."),(0,n.kt)("p",null,"First, retrieve the certificate that Rancher is using and place in a file named ",(0,n.kt)("inlineCode",{parentName:"p"},"ca-additional.pem"),". If you are using the Rancher-generated certs option, this can be done with the following command:"),(0,n.kt)("pre",null,(0,n.kt)("code",{parentName:"pre",className:"language-bash"},'kubectl get secret tls-rancher -n cattle-system -o jsonpath="{.data.tls\\.crt}" | base64 -d >> ca-additional.pem\n')),(0,n.kt)("p",null,"Then, create a secret which uses this cert:"),(0,n.kt)("pre",null,(0,n.kt)("code",{parentName:"pre",className:"language-bash"},"kubectl -n cattle-csp-adapter-system create secret generic tls-ca-additional --from-file=ca-additional.pem\n")),(0,n.kt)("blockquote",null,(0,n.kt)("p",{parentName:"blockquote"},(0,n.kt)("strong",{parentName:"p"},"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.")),(0,n.kt)("h3",{id:"4-install-the-chart"},"4. Install the Chart"),(0,n.kt)("p",null,"First, add the ",(0,n.kt)("inlineCode",{parentName:"p"},"rancher/charts")," repo using the following command:"),(0,n.kt)("pre",null,(0,n.kt)("code",{parentName:"pre",className:"language-bash"},"helm repo add rancher-charts https://charts.rancher.io\n")),(0,n.kt)("p",null,"Next, install the CSP adapter. You must specify several values, including the account number, and the name of the role created in the prerequisites."),(0,n.kt)("p",null,"Ensure that you use the version of the CSP adapter that matches the version of Rancher that you are running, as defined ",(0,n.kt)("a",{parentName:"p",href:"#rancher-vs-adapter-compatibility-matrix"},"above"),"."),(0,n.kt)("p",null,"For the below instructions, replace ",(0,n.kt)("inlineCode",{parentName:"p"},"$MY_ACC_NUM")," with your AWS account number and ",(0,n.kt)("inlineCode",{parentName:"p"},"$MY_ROLE_NAME")," with the name of the role created in the prerequisites. In addition, replace ",(0,n.kt)("inlineCode",{parentName:"p"},"$CSP_ADAPTER_VERSION")," with the version that matches your Rancher version in the ",(0,n.kt)("a",{parentName:"p",href:"#rancher-vs-adapter-compatibility-matrix"},"version matrix"),"."),(0,n.kt)("blockquote",null,(0,n.kt)("p",{parentName:"blockquote"},(0,n.kt)("strong",{parentName:"p"},"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.')),(0,n.kt)("blockquote",null,(0,n.kt)("p",{parentName:"blockquote"},(0,n.kt)("strong",{parentName:"p"},"Note:")," Accounts using the AWS Marketplace listing for the EU and the UK will need to specify an additional ",(0,n.kt)("inlineCode",{parentName:"p"},"--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.")),(0,n.kt)(u,{mdxType:"Tabs"},(0,n.kt)(d,{value:"Let's Encrypt/ Public Certificate Authority",mdxType:"TabItem"},(0,n.kt)("pre",null,(0,n.kt)("code",{parentName:"pre",className:"language-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 --version $CSP_ADAPTER_VERSION\n")),(0,n.kt)("p",null," Alternatively, you can use a ",(0,n.kt)("inlineCode",{parentName:"p"},"values.yaml")," and specify options like below:"),(0,n.kt)("pre",null,(0,n.kt)("code",{parentName:"pre",className:"language-yaml"},'aws:\n enabled: true\n accountNumber: "$MY_ACC_NUM"\n roleName: $MY_ROLE_NAME\n')),(0,n.kt)("blockquote",null,(0,n.kt)("p",{parentName:"blockquote"},(0,n.kt)("strong",{parentName:"p"},"Note:")," The account number needs to be specified in a string format, like the above, or the installation will fail.")),(0,n.kt)("p",null," You can then install the adapter with the following command:"),(0,n.kt)("pre",null,(0,n.kt)("code",{parentName:"pre",className:"language-bash"},"helm install rancher-csp-adapter rancher-charts/rancher-csp-adapter -f values.yaml --version $CSP_ADAPTER_VERSION\n"))),(0,n.kt)(d,{value:"Private CA Authority / Rancher-generated Certificates",mdxType:"TabItem"},(0,n.kt)("pre",null,(0,n.kt)("code",{parentName:"pre",className:"language-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 --version $CSP_ADAPTER_VERSION\n")),(0,n.kt)("p",null," Alternatively, you can use a ",(0,n.kt)("inlineCode",{parentName:"p"},"values.yaml")," and specify options the below:"),(0,n.kt)("pre",null,(0,n.kt)("code",{parentName:"pre",className:"language-yaml"},'aws:\n enabled: true\n accountNumber: "$MY_ACC_NUM"\n roleName: $MY_ROLE_NAME\nadditionalTrustedCAs: true\n')),(0,n.kt)("blockquote",null,(0,n.kt)("p",{parentName:"blockquote"},(0,n.kt)("strong",{parentName:"p"},"Note:")," The account number needs to be specified in a string format, like the above, or the installation will fail.")),(0,n.kt)("p",null," You can then install the adapter with the following command:"),(0,n.kt)("pre",null,(0,n.kt)("code",{parentName:"pre",className:"language-bash"},"helm install rancher-csp-adapter rancher-charts/rancher-csp-adapter -f values.yaml --version $CSP_ADAPTER_VERSION\n")))),(0,n.kt)("h3",{id:"5-managing-certificate-updates"},"5. Managing Certificate Updates"),(0,n.kt)("p",null,"If you had to create a secret storing a custom cert in ",(0,n.kt)("a",{parentName:"p",href:"#3-create-certificate-secrets"},"Step 3"),", you will need to update this secret over time as the certificate is rotated."),(0,n.kt)("p",null,"First, delete the original secret in the cattle-csp-adapter-system namespace, using the below command:"),(0,n.kt)("pre",null,(0,n.kt)("code",{parentName:"pre",className:"language-bash"},"kubectl delete secret tls-ca-additional -n cattle-csp-adapter-system\n")),(0,n.kt)("p",null,"Then, follow the original installation steps in ",(0,n.kt)("a",{parentName:"p",href:"#3-create-certificate-secrets"},"Step 3")," to replace the content of the secret with the updated value."),(0,n.kt)("p",null,"Finally, restart the rancher-csp-adapter deployment to ensure that the updated value is made available to the adapter:"),(0,n.kt)("pre",null,(0,n.kt)("code",{parentName:"pre",className:"language-bash"},"kubectl rollout restart deploy rancher-csp-adapter -n cattle-csp-adapter-system\n")),(0,n.kt)("blockquote",null,(0,n.kt)("p",{parentName:"blockquote"},(0,n.kt)("strong",{parentName:"p"},"Note:")," There are methods such as cert-manager's ",(0,n.kt)("a",{parentName:"p",href:"https://cert-manager.io/docs/projects/trust/"},"trust operator")," 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.")))}m.isMDXComponent=!0}}]); |