From a0c5126214be977fd303d141179675fa4b88a5aa Mon Sep 17 00:00:00 2001 From: Jennifer Travinski Date: Fri, 13 May 2022 11:10:18 -0400 Subject: [PATCH 1/2] Removed Rancher CLI from QS; added to main CLI page for 2.5, 2.6 --- content/rancher/v2.5/en/cli/_index.md | 58 +++++++++++++++---- .../v2.5/en/quick-start-guide/_index.md | 2 - .../v2.5/en/quick-start-guide/cli/_index.md | 41 ------------- content/rancher/v2.6/en/cli/_index.md | 40 ++++++++++++- .../v2.6/en/quick-start-guide/_index.md | 2 - .../v2.6/en/quick-start-guide/cli/_index.md | 39 ------------- 6 files changed, 84 insertions(+), 98 deletions(-) delete mode 100644 content/rancher/v2.5/en/quick-start-guide/cli/_index.md delete mode 100644 content/rancher/v2.6/en/quick-start-guide/cli/_index.md diff --git a/content/rancher/v2.5/en/cli/_index.md b/content/rancher/v2.5/en/cli/_index.md index 0413cdde5ed..cb66982e658 100644 --- a/content/rancher/v2.5/en/cli/_index.md +++ b/content/rancher/v2.5/en/cli/_index.md @@ -1,11 +1,9 @@ --- -title: Using the Rancher Command Line Interface +title: Rancher Command Line Interface description: The Rancher CLI is a unified tool that you can use to interact with Rancher. With it, you can operate Rancher using a command line interface rather than the GUI -metaTitle: "Using the Rancher Command Line Interface " +metaTitle: "Using the Rancher Command Line Interface" metaDescription: "The Rancher CLI is a unified tool that you can use to interact with Rancher. With it, you can operate Rancher using a command line interface rather than the GUI" weight: 21 -aliases: - - /rancher/v2.5/en/cluster-admin/cluster-access/cli --- The Rancher CLI (Command Line Interface) is a unified tool that you can use to interact with Rancher. With this tool, you can operate Rancher using a command line rather than the GUI. @@ -38,11 +36,11 @@ Before you can perform any commands, you must select a Rancher project to perfor **Example: `./rancher context switch` Output** ``` User:rancher-cli-directory user$ ./rancher context switch -NUMBER CLUSTER NAME PROJECT ID PROJECT NAME -1 cluster-2 c-7q96s:p-h4tmb project-2 -2 cluster-2 c-7q96s:project-j6z6d Default -3 cluster-1 c-lchzv:p-xbpdt project-1 -4 cluster-1 c-lchzv:project-s2mch Default +NUMBER CLUSTER NAME PROJECT ID PROJECT NAME +1 cluster-2 c-7q96s:p-h4tmb project-2 +2 cluster-2 c-7q96s:project-j6z6d Default +3 cluster-1 c-lchzv:p-xbpdt project-1 +4 cluster-1 c-lchzv:project-s2mch Default Select a Project: ``` @@ -59,8 +57,8 @@ The following commands are available for use in Rancher CLI. | Command | Result | |---|---| -| `apps, [app]` | Performs operations on catalog applications (i.e. individual [Helm charts](https://docs.helm.sh/developing_charts/) or Rancher charts. | -| `catalog` | Performs operations on [catalogs]({{}}/rancher/v2.5/en/catalog/). | +| `apps, [app]` | Performs operations on catalog applications (i.e., individual [Helm charts](https://docs.helm.sh/developing_charts/)) or Rancher charts. | +| `catalog` | Performs operations on [catalogs]({{}}/rancher/v2.5/en/helm-charts/). | | `clusters, [cluster]` | Performs operations on your [clusters]({{}}/rancher/v2.5/en/cluster-provisioning/). | | `context` | Switches between Rancher [projects]({{}}/rancher/v2.5/en/cluster-admin/projects-and-namespaces/). For an example, see [Project Selection](#project-selection). | | `inspect [OPTIONS] [RESOURCEID RESOURCENAME]` | Displays details about [Kubernetes resources](https://kubernetes.io/docs/reference/kubectl/cheatsheet/#resource-types) or Rancher resources (i.e.: [projects]({{}}/rancher/v2.5/en/cluster-admin/projects-and-namespaces/) and [workloads]({{}}/rancher/v2.5/en/k8s-in-rancher/workloads/)). Specify resources by name or ID. | @@ -80,3 +78,41 @@ The following commands are available for use in Rancher CLI. Once logged into Rancher Server using the CLI, enter `./rancher --help` for a list of commands. All commands accept the `--help` flag, which documents each command's usage. + +### Limitations + +The Rancher CLI **cannot** be used to install [dashboard apps or Rancher feature charts](../helm-charts/). + +# Using the CLI with Rancher + +Interact with Rancher using command line interface (CLI) tools from your workstation. + +### Rancher CLI + +Ensure you can run `rancher kubectl get pods` successfully. + +### kubectl + +Install the `kubectl` utility. See [install kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/). + +Configure kubectl by visiting your cluster in the Rancher Web UI, clicking on `Kubeconfig`, copying contents, and putting them into your `~/.kube/config` file. + +Run `kubectl cluster-info` or `kubectl get pods` successfully. + +### Authentication with kubectl and kubeconfig Tokens with TTL + +_Requirements_ + +If admins have [enforced TTL on kubeconfig tokens]({{}}/rancher/v2.5/en/api/api-tokens/#setting-ttl-on-kubeconfig-tokens), the kubeconfig file requires the [Rancher CLI](../cli) to be present in your PATH when you run `kubectl`. Otherwise, you’ll see an error like: +`Unable to connect to the server: getting credentials: exec: exec: "rancher": executable file not found in $PATH`. + +This feature enables kubectl to authenticate with the Rancher server and get a new kubeconfig token when required. The following auth providers are currently supported: + +1. Local +2. Active Directory +3. FreeIpa, OpenLdap +4. SAML providers - Ping, Okta, ADFS, Keycloak, Shibboleth + +When you first run kubectl, for example, `kubectl get pods`, it will ask you to pick an auth provider and log in with the Rancher server. +The kubeconfig token is cached in the path where you run kubectl under `./.cache/token`. This token is valid until [it expires](../../api/api-tokens/#setting-ttl-on-kubeconfig-tokens-period), or [gets deleted from the Rancher server](../../api/api-tokens/#deleting-tokens). +Upon expiration, the next `kubectl get pods` will ask you to log in with the Rancher server again. diff --git a/content/rancher/v2.5/en/quick-start-guide/_index.md b/content/rancher/v2.5/en/quick-start-guide/_index.md index 7e1ae5e682e..6e8bb1f38ee 100644 --- a/content/rancher/v2.5/en/quick-start-guide/_index.md +++ b/content/rancher/v2.5/en/quick-start-guide/_index.md @@ -13,5 +13,3 @@ We have Quick Start Guides for: - [Deploying Rancher Server]({{}}/rancher/v2.5/en/quick-start-guide/deployment/): Get started running Rancher using the method most convenient for you. - [Deploying Workloads]({{}}/rancher/v2.5/en/quick-start-guide/workload/): Deploy a simple [workload](https://kubernetes.io/docs/concepts/workloads/) and expose it, letting you access it from outside the cluster. - -- [Using the CLI]({{}}/rancher/v2.5/en/quick-start-guide/cli/): Use `kubectl` or Rancher command line interface (CLI) to interact with your Rancher instance. diff --git a/content/rancher/v2.5/en/quick-start-guide/cli/_index.md b/content/rancher/v2.5/en/quick-start-guide/cli/_index.md deleted file mode 100644 index 954e27f6a70..00000000000 --- a/content/rancher/v2.5/en/quick-start-guide/cli/_index.md +++ /dev/null @@ -1,41 +0,0 @@ ---- -title: CLI with Rancher -weight: 100 -aliases: - - /rancher/v2.x/en/quick-start-guide/cli/ ---- - -Interact with Rancher using command line interface (CLI) tools from your workstation. - -## Rancher CLI - -Follow the steps in [rancher cli](../../cli). - -Ensure you can run `rancher kubectl get pods` successfully. - - -## kubectl -Install the `kubectl` utility. See [install kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/). - - -Configure kubectl by visiting your cluster in the Rancher Web UI then clicking on `Kubeconfig`, copying contents and putting into your `~/.kube/config` file. - -Run `kubectl cluster-info` or `kubectl get pods` successfully. - -## Authentication with kubectl and kubeconfig Tokens with TTL - -_Requirements_ - -If admins have [enforced TTL on kubeconfig tokens]({{}}/rancher/v2.5/en/api/api-tokens/#setting-ttl-on-kubeconfig-tokens), the kubeconfig file requires the [Rancher cli](../cli) to be present in your PATH when you run `kubectl`. Otherwise, you’ll see error like: -`Unable to connect to the server: getting credentials: exec: exec: "rancher": executable file not found in $PATH`. - -This feature enables kubectl to authenticate with the Rancher server and get a new kubeconfig token when required. The following auth providers are currently supported: - -1. Local -2. Active Directory -3. FreeIpa, OpenLdap -4. SAML providers - Ping, Okta, ADFS, Keycloak, Shibboleth - -When you first run kubectl, for example, `kubectl get pods`, it will ask you to pick an auth provider and log in with the Rancher server. -The kubeconfig token is cached in the path where you run kubectl under `./.cache/token`. This token is valid till [it expires](../../api/api-tokens/#setting-ttl-on-kubeconfig-tokens-period), or [gets deleted from the Rancher server](../../api/api-tokens/#deleting-tokens) -Upon expiration, the next `kubectl get pods` will ask you to log in with the Rancher server again. diff --git a/content/rancher/v2.6/en/cli/_index.md b/content/rancher/v2.6/en/cli/_index.md index 8998916acd2..f039804ffe2 100644 --- a/content/rancher/v2.6/en/cli/_index.md +++ b/content/rancher/v2.6/en/cli/_index.md @@ -1,7 +1,7 @@ --- -title: Using the Rancher Command Line Interface +title: Rancher Command Line Interface description: The Rancher CLI is a unified tool that you can use to interact with Rancher. With it, you can operate Rancher using a command line interface rather than the GUI -metaTitle: "Using the Rancher Command Line Interface " +metaTitle: "Using the Rancher Command Line Interface" metaDescription: "The Rancher CLI is a unified tool that you can use to interact with Rancher. With it, you can operate Rancher using a command line interface rather than the GUI" weight: 21 --- @@ -63,7 +63,7 @@ The following commands are available for use in Rancher CLI. | Command | Result | |---|---| -| `apps, [app]` | Performs operations on catalog applications (i.e. individual [Helm charts](https://docs.helm.sh/developing_charts/) or Rancher charts. | +| `apps, [app]` | Performs operations on catalog applications (i.e., individual [Helm charts](https://docs.helm.sh/developing_charts/)) or Rancher charts. | | `catalog` | Performs operations on [catalogs]({{}}/rancher/v2.6/en/helm-charts/). | | `clusters, [cluster]` | Performs operations on your [clusters]({{}}/rancher/v2.6/en/cluster-provisioning/). | | `context` | Switches between Rancher [projects]({{}}/rancher/v2.6/en/cluster-admin/projects-and-namespaces/). For an example, see [Project Selection](#project-selection). | @@ -88,3 +88,37 @@ All commands accept the `--help` flag, which documents each command's usage. ### Limitations The Rancher CLI **cannot** be used to install [dashboard apps or Rancher feature charts](../helm-charts/). + +# Using the CLI with Rancher + +Interact with Rancher using command line interface (CLI) tools from your workstation. + +### Rancher CLI + +Ensure you can run `rancher kubectl get pods` successfully. + +### kubectl + +Install the `kubectl` utility. See [install kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/). + +Configure kubectl by visiting your cluster in the Rancher Web UI, clicking on `Kubeconfig`, copying contents, and putting them into your `~/.kube/config` file. + +Run `kubectl cluster-info` or `kubectl get pods` successfully. + +### Authentication with kubectl and kubeconfig Tokens with TTL + +_Requirements_ + +If admins have [enforced TTL on kubeconfig tokens]({{}}/rancher/v2.6/en/api/api-tokens/#setting-ttl-on-kubeconfig-tokens), the kubeconfig file requires the [Rancher CLI](../cli) to be present in your PATH when you run `kubectl`. Otherwise, you’ll see an error like: +`Unable to connect to the server: getting credentials: exec: exec: "rancher": executable file not found in $PATH`. + +This feature enables kubectl to authenticate with the Rancher server and get a new kubeconfig token when required. The following auth providers are currently supported: + +1. Local +2. Active Directory +3. FreeIpa, OpenLdap +4. SAML providers - Ping, Okta, ADFS, Keycloak, Shibboleth + +When you first run kubectl, for example, `kubectl get pods`, it will ask you to pick an auth provider and log in with the Rancher server. +The kubeconfig token is cached in the path where you run kubectl under `./.cache/token`. This token is valid until [it expires](../../api/api-tokens/#setting-ttl-on-kubeconfig-tokens-period), or [gets deleted from the Rancher server](../../api/api-tokens/#deleting-tokens). +Upon expiration, the next `kubectl get pods` will ask you to log in with the Rancher server again. diff --git a/content/rancher/v2.6/en/quick-start-guide/_index.md b/content/rancher/v2.6/en/quick-start-guide/_index.md index fe180303614..b6b0ba33866 100644 --- a/content/rancher/v2.6/en/quick-start-guide/_index.md +++ b/content/rancher/v2.6/en/quick-start-guide/_index.md @@ -15,5 +15,3 @@ We have Quick Start Guides for: - [Deploying Rancher Server]({{}}/rancher/v2.6/en/quick-start-guide/deployment/): Get started running Rancher using the method most convenient for you. - [Deploying Workloads]({{}}/rancher/v2.6/en/quick-start-guide/workload/): Deploy a simple [workload](https://kubernetes.io/docs/concepts/workloads/) and expose it, letting you access it from outside the cluster. - -- [Using the CLI]({{}}/rancher/v2.6/en/quick-start-guide/cli/): Use `kubectl` or Rancher command line interface (CLI) to interact with your Rancher instance. diff --git a/content/rancher/v2.6/en/quick-start-guide/cli/_index.md b/content/rancher/v2.6/en/quick-start-guide/cli/_index.md deleted file mode 100644 index c0787bc4c08..00000000000 --- a/content/rancher/v2.6/en/quick-start-guide/cli/_index.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -title: CLI with Rancher -weight: 100 ---- - -Interact with Rancher using command line interface (CLI) tools from your workstation. - -## Rancher CLI - -Follow the steps in [rancher cli](../../cli). - -Ensure you can run `rancher kubectl get pods` successfully. - - -## kubectl -Install the `kubectl` utility. See [install kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/). - - -Configure kubectl by visiting your cluster in the Rancher Web UI then clicking on `Kubeconfig`, copying contents and putting into your `~/.kube/config` file. - -Run `kubectl cluster-info` or `kubectl get pods` successfully. - -## Authentication with kubectl and kubeconfig Tokens with TTL - -_Requirements_ - -If admins have [enforced TTL on kubeconfig tokens]({{}}/rancher/v2.6/en/api/api-tokens/#setting-ttl-on-kubeconfig-tokens), the kubeconfig file requires the [Rancher cli](../cli) to be present in your PATH when you run `kubectl`. Otherwise, you’ll see error like: -`Unable to connect to the server: getting credentials: exec: exec: "rancher": executable file not found in $PATH`. - -This feature enables kubectl to authenticate with the Rancher server and get a new kubeconfig token when required. The following auth providers are currently supported: - -1. Local -2. Active Directory -3. FreeIpa, OpenLdap -4. SAML providers - Ping, Okta, ADFS, Keycloak, Shibboleth - -When you first run kubectl, for example, `kubectl get pods`, it will ask you to pick an auth provider and log in with the Rancher server. -The kubeconfig token is cached in the path where you run kubectl under `./.cache/token`. This token is valid till [it expires](../../api/api-tokens/#setting-ttl-on-kubeconfig-tokens-period), or [gets deleted from the Rancher server](../../api/api-tokens/#deleting-tokens) -Upon expiration, the next `kubectl get pods` will ask you to log in with the Rancher server again. From ee8b7fce32b9692292aaeab228d4a2be4de5f31c Mon Sep 17 00:00:00 2001 From: Jennifer Travinski Date: Fri, 13 May 2022 15:39:15 -0400 Subject: [PATCH 2/2] Updated sections and corrected nits per feedback --- content/rancher/v2.5/en/cli/_index.md | 39 ++++++++++++++++--------- content/rancher/v2.6/en/cli/_index.md | 41 ++++++++++++++++----------- 2 files changed, 50 insertions(+), 30 deletions(-) diff --git a/content/rancher/v2.5/en/cli/_index.md b/content/rancher/v2.5/en/cli/_index.md index cb66982e658..6996b6bdf3d 100644 --- a/content/rancher/v2.5/en/cli/_index.md +++ b/content/rancher/v2.5/en/cli/_index.md @@ -1,11 +1,23 @@ --- -title: Rancher Command Line Interface -description: The Rancher CLI is a unified tool that you can use to interact with Rancher. With it, you can operate Rancher using a command line interface rather than the GUI -metaTitle: "Using the Rancher Command Line Interface" -metaDescription: "The Rancher CLI is a unified tool that you can use to interact with Rancher. With it, you can operate Rancher using a command line interface rather than the GUI" +title: CLI with Rancher +description: Interact with Rancher using command line interface (CLI) tools from your workstation. weight: 21 --- +- [Rancher CLI](#rancher-cli) + - [Download Rancher CLI](#download-rancher-cli) + - [Requirements](#requirements) + - [CLI Authentication](#cli-authentication) + - [Project Selection](#project-selection) + - [Commands](#commands) + - [Rancher CLI Help](#rancher-cli-help) + - [Limitations](#limitations) +- [kubectl](#kubectl) + - [kubectl Utility](#kubectl-utility) + - [Authentication with kubectl and kubeconfig Tokens with TTL](#authentication-with-kubectl-and-kubeconfig-tokens-with-ttl) + +# Rancher CLI + The Rancher CLI (Command Line Interface) is a unified tool that you can use to interact with Rancher. With this tool, you can operate Rancher using a command line rather than the GUI. ### Download Rancher CLI @@ -51,6 +63,8 @@ INFO[0005] Setting new context to project project-1 INFO[0005] Saving config to /Users/markbishop/.rancher/cli2.json ``` +Ensure you can run `rancher kubectl get pods` successfully. + ### Commands The following commands are available for use in Rancher CLI. @@ -83,15 +97,11 @@ All commands accept the `--help` flag, which documents each command's usage. The Rancher CLI **cannot** be used to install [dashboard apps or Rancher feature charts](../helm-charts/). -# Using the CLI with Rancher +# kubectl -Interact with Rancher using command line interface (CLI) tools from your workstation. +Interact with Rancher using kubectl. -### Rancher CLI - -Ensure you can run `rancher kubectl get pods` successfully. - -### kubectl +### kubectl Utility Install the `kubectl` utility. See [install kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/). @@ -109,9 +119,10 @@ If admins have [enforced TTL on kubeconfig tokens]({{}}/rancher/v2.5/en This feature enables kubectl to authenticate with the Rancher server and get a new kubeconfig token when required. The following auth providers are currently supported: 1. Local -2. Active Directory -3. FreeIpa, OpenLdap -4. SAML providers - Ping, Okta, ADFS, Keycloak, Shibboleth +2. Active Directory (LDAP only) +3. FreeIPA +4. OpenLDAP +5. SAML providers: Ping, Okta, ADFS, Keycloak, Shibboleth When you first run kubectl, for example, `kubectl get pods`, it will ask you to pick an auth provider and log in with the Rancher server. The kubeconfig token is cached in the path where you run kubectl under `./.cache/token`. This token is valid until [it expires](../../api/api-tokens/#setting-ttl-on-kubeconfig-tokens-period), or [gets deleted from the Rancher server](../../api/api-tokens/#deleting-tokens). diff --git a/content/rancher/v2.6/en/cli/_index.md b/content/rancher/v2.6/en/cli/_index.md index f039804ffe2..553cb44c5c2 100644 --- a/content/rancher/v2.6/en/cli/_index.md +++ b/content/rancher/v2.6/en/cli/_index.md @@ -1,19 +1,29 @@ --- -title: Rancher Command Line Interface -description: The Rancher CLI is a unified tool that you can use to interact with Rancher. With it, you can operate Rancher using a command line interface rather than the GUI -metaTitle: "Using the Rancher Command Line Interface" -metaDescription: "The Rancher CLI is a unified tool that you can use to interact with Rancher. With it, you can operate Rancher using a command line interface rather than the GUI" +title: CLI with Rancher +description: Interact with Rancher using command line interface (CLI) tools from your workstation. weight: 21 --- +- [Rancher CLI](#rancher-cli) + - [Download Rancher CLI](#download-rancher-cli) + - [Requirements](#requirements) + - [CLI Authentication](#cli-authentication) + - [Project Selection](#project-selection) + - [Commands](#commands) + - [Rancher CLI Help](#rancher-cli-help) + - [Limitations](#limitations) +- [kubectl](#kubectl) + - [kubectl Utility](#kubectl-utility) + - [Authentication with kubectl and kubeconfig Tokens with TTL](#authentication-with-kubectl-and-kubeconfig-tokens-with-ttl) + +# Rancher CLI + The Rancher CLI (Command Line Interface) is a unified tool that you can use to interact with Rancher. With this tool, you can operate Rancher using a command line rather than the GUI. ### Download Rancher CLI The binary can be downloaded directly from the UI. The link can be found in the right hand side of the footer in the UI. We have binaries for Windows, Mac, and Linux. You can also check the [releases page for our CLI](https://github.com/rancher/cli/releases) for direct downloads of the binary. -The binary can be downloaded directly from the UI. - 1. In the upper left corner, click **☰**. 1. At the bottom, click **v2.6.x**, where **v2.6.x** is a hyperlinked text indicating the installed Rancher version. 1. Under the **CLI Downloads section**, there are links to download the binaries for Windows, Mac, and Linux. You can also check the [releases page for our CLI](https://github.com/rancher/cli/releases) for direct downloads of the binary. @@ -57,6 +67,8 @@ INFO[0005] Setting new context to project project-1 INFO[0005] Saving config to /Users/markbishop/.rancher/cli2.json ``` +Ensure you can run `rancher kubectl get pods` successfully. + ### Commands The following commands are available for use in Rancher CLI. @@ -89,15 +101,11 @@ All commands accept the `--help` flag, which documents each command's usage. The Rancher CLI **cannot** be used to install [dashboard apps or Rancher feature charts](../helm-charts/). -# Using the CLI with Rancher +# kubectl -Interact with Rancher using command line interface (CLI) tools from your workstation. +Interact with Rancher using kubectl. -### Rancher CLI - -Ensure you can run `rancher kubectl get pods` successfully. - -### kubectl +### kubectl Utility Install the `kubectl` utility. See [install kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/). @@ -115,9 +123,10 @@ If admins have [enforced TTL on kubeconfig tokens]({{}}/rancher/v2.6/en This feature enables kubectl to authenticate with the Rancher server and get a new kubeconfig token when required. The following auth providers are currently supported: 1. Local -2. Active Directory -3. FreeIpa, OpenLdap -4. SAML providers - Ping, Okta, ADFS, Keycloak, Shibboleth +2. Active Directory (LDAP only) +3. FreeIPA +4. OpenLDAP +5. SAML providers: Ping, Okta, ADFS, Keycloak, Shibboleth When you first run kubectl, for example, `kubectl get pods`, it will ask you to pick an auth provider and log in with the Rancher server. The kubeconfig token is cached in the path where you run kubectl under `./.cache/token`. This token is valid until [it expires](../../api/api-tokens/#setting-ttl-on-kubeconfig-tokens-period), or [gets deleted from the Rancher server](../../api/api-tokens/#deleting-tokens).