diff --git a/docs/.vuepress/sidebar-menus/user-guide.ts b/docs/.vuepress/sidebar-menus/user-guide.ts index e388007b2..8572e1994 100644 --- a/docs/.vuepress/sidebar-menus/user-guide.ts +++ b/docs/.vuepress/sidebar-menus/user-guide.ts @@ -225,7 +225,8 @@ export default [{ {text: 'Datadog', link:'/manual/plugins/datadog-plugins-overview.md'}, {text: 'Google Cloud', link: '/manual/plugins/gcp-plugins-overview.md'}, {text: 'Jira', link: '/manual/plugins/jira-plugins-overview.md'}, - {text: 'Kubernetes', link: '/manual/plugins/kubernetes-plugins-overview.md'}, + {text: 'Kubernetes (Commercial)', link: '/manual/plugins/kubernetes-plugins-overview.md'}, + {text: 'Kubernetes (Open Source)', link: '/manual/plugins/kubernetes-open-source.md'}, {text: 'PagerDuty', link: '/manual/plugins/pagerduty-plugins-overview.md'}, {text: 'Sensu', link: '/manual/plugins/sensu-plugins-overview.md'}, {text: 'ServiceNow', link: '/manual/plugins/servicenow-plugins-overview.md'}, diff --git a/docs/administration/runner/runner-installation/runner-install.md b/docs/administration/runner/runner-installation/runner-install.md index c52370d3f..ce7039d31 100644 --- a/docs/administration/runner/runner-installation/runner-install.md +++ b/docs/administration/runner/runner-installation/runner-install.md @@ -239,7 +239,7 @@ spec: - touch this_is_from_rundeck_runner restartPolicy: Always ``` -6. Creat the deployment: **`kubectl create -f deployment.yml`**. +6. Create the deployment: **`kubectl apply -f deployment.yml`**. 7. Confirm that the Runner was deployed successfully: **`kubectl logs -f rundeck-runner --namespace=[NAMESPACE]`** 8. Verify that the Runner is communicating with Runbook Automation correctly by looking in the **Status** column on the Runner Management page: ![Runner installed correctly](/assets/img/runner-installed-k8s.png) diff --git a/docs/manual/plugins/kubernetes-open-source.md b/docs/manual/plugins/kubernetes-open-source.md new file mode 100644 index 000000000..9cb245cd7 --- /dev/null +++ b/docs/manual/plugins/kubernetes-open-source.md @@ -0,0 +1,127 @@ +# Kubernetes Plugins for Rundeck Community +![](/assets/img/kubernetes-icon.png) + +Rundeck integrates with Kubernetes through a variety of plugins. By integrating Rundeck with Kubernetes, users can automate and provide self-service interfaces for operations in their Kubernetes Clusters. + +:::warning Commercial Kubernetes Plugins +This document covers the plugins available in Rundeck Community (open source). If you are using one of the commercial Runbook Automation products, see documentation for the [**Commercial Kubernetes plugins**](/manual/plugins/kubernetes-plugins-overview.md). +::: + +## Open Source Kubernetes Plugins +
List of Open Source Plugins + + +**Available in Rundeck Open Source** + +|Plugin Name| Plugin Type| Description| +|:---------------------------------------------------------|:---------------------------------------------------------:|:---------------------------------------------------------| +|[**Create Deployment**](/manual/jobs/job-plugins/node-steps/kubernetes-deployment-plugins.md#kubernetes-deployment-create)|Node Step|Create a new deployment.| +|[**Delete Deployment**](/manual/jobs/job-plugins/node-steps/kubernetes-deployment-plugins.md#kubernetes-deployment-delete)|Node Step|Delete an existing deployment.| +|[**Deployment Status**](/manual/jobs/job-plugins/node-steps/kubernetes-deployment-plugins.md#kubernetes-deployment-status)|Node Step|Get the status of an existing deployment.| +|[**Update Deployment**](/manual/jobs/job-plugins/node-steps/kubernetes-deployment-plugins.md#kubernetes-deployment-update)|Node Step|Update an existing deployment.| +|[**Waitfor Deployment**](/manual/jobs/job-plugins/node-steps/kubernetes-deployment-plugins.md#kubernetes-deployment-waitfor)|Node Step|Pause workflow until deployment is complete.| +|[**Create Job**](/manual/jobs/job-plugins/node-steps/kubernetes-job-plugins.md#kubernetes-job-create)|Node Step|Create a new Kubernetes job.| +|[**Delete Job**](/manual/jobs/job-plugins/node-steps/kubernetes-job-plugins.md#kubernetes-job-delete)|Node Step|Delete an existing Kubernetes job.| +|[**Re-run Job**](/manual/jobs/job-plugins/node-steps/kubernetes-job-plugins.md#kubernetes-job-re-run)|Node Step|Re-runs an existing Kubernetes job.| +|[**Waitfor Job**](/manual/jobs/job-plugins/node-steps/kubernetes-job-plugins.md#kubernetes-job-waitfor)|Node Step|Pause workflow until Kubernetes job is complete.| +|[**Create Service**](/manual/jobs/job-plugins/node-steps/kubernetes-service-plugins.md#kubernetes-service-create)|Node Step|Create a new Kubernetes service.| +|[**Update Service**](/manual/jobs/job-plugins/node-steps/kubernetes-service-plugins.md#kubernetes-service-update)|Node Step|Update an existing Kubernetes service.| +|[**Delete Service**](/manual/jobs/job-plugins/node-steps/kubernetes-service-plugins.md#kubernetes-service-delete)|Node Step|Delete an existing Kubernetes service.| +|[**Pods Node Source**](/manual/projects/resource-model-sources/kubernetes.md)|Resource Model|Populates node inventory with Kubernetes pods.| +|[**Create Pod**](/manual/jobs/job-plugins/node-steps/kubernetes-pod-plugins.md#kubernetes-pod-create)|Node Step|Create a new Kubernetes pod.| +|[**Delete Pod**](/manual/jobs/job-plugins/node-steps/kubernetes-pod-plugins.md#kubernetes-pod-delete)|Node Step|Delete an existing Kubernetes pod.| +|[**Describe Pod**](/manual/jobs/job-plugins/node-steps/kubernetes-pod-plugins.md#kubernetes-pod-describe)|Node Step|Describe a running Kubernetes pod.| +|[**Execute Command**](/manual/jobs/job-plugins/node-steps/kubernetes-pod-plugins.md#kubernetes-pod-execute-command)|Node Step|Execute a command inside a container in a running pod.| +|[**Execute Script**](/manual/jobs/job-plugins/node-steps/kubernetes-pod-plugins.md#kubernetes-pod-execute-script)|Node Step|Execute a script inside a container in a running pod.| +|[**Pod Logs**](/manual/jobs/job-plugins/node-steps/kubernetes-pod-plugins.md#kubernetes-pod-logs)|Node Step|View the logs of a running pod.| +|[**Waitfor Pod**](/manual/jobs/job-plugins/node-steps/kubernetes-pod-plugins.md#kubernetes-pod-waitfor)|Node Step|Pause workflow until pod is in "ready" state.| +|[**Debug Pod**](/manual/jobs/job-plugins/node-steps/kubernetes-debug-plugins.md#kubernetes-debug-ephemeral-container)|Node Step|Debug a running container inside an existing pod using an ephemeral container.| +|[**Waitfor StatefulSet**](/manual/jobs/job-plugins/node-steps/kubernetes-statefulset-plugins.md#kubernetes-statefulset-waitfor)|Node Step|Pause workflow until StatefulSet has been successfully deployed.| + +**Plugins available only in Commercial products** +> Note: All Open Source plugins also included. + +|Plugin Name| Plugin Type| Description| +|:---------------------------------------------------------|:---------------------------------------------------------:|:---------------------------------------------------------| +|[**Amazon EKS Node Source**](/manual/projects/resource-model-sources/aws-eks.md)|Node Source|Imports Amazon Web Services EKS Clusters as Nodes.| +|[**Azure AKS Node Source**](/manual/projects/resource-model-sources/azure-aks.md)|Node Source|Imports Azure AKS Clusters as Nodes.| +|[**Google Cloud GKE Node Source**](/manual/projects/resource-model-sources/gcp-gke.md)|Node Source|Imports Google Cloud GKE Clusters as Nodes.| +|[**Kubernetes Cluster Create Object**](/manual/jobs/job-plugins/node-steps/kubernetes-create-object)|Node Step|This plugin creates an object of a selected kind within a Kubernetes cluster.| +|[**Kubernetes Cluster Delete Object**](/manual/jobs/job-plugins/node-steps/kubernetes-delete-object)|Node Step|This plugin deletes an object of a selected kind within a Kubernetes cluster.| +|[**Kubernetes Cluster Describe Object**](/manual/jobs/job-plugins/node-steps/kubernetes-describe-object)|Node Step|This plugin describes an object of a selected kind within a Kubernetes cluster.| +|[**Kubernetes Cluster List Objects**](/manual/jobs/job-plugins/node-steps/kubernetes-list-objects)|Node Step|This plugin lists objects of a selected kind within a Kubernetes cluster.| +|[**Kubernetes Cluster Object Logs**](/manual/jobs/job-plugins/node-steps/kubernetes-object-logs)|This plugin allows you to view the logs of an object within a Kubernetes cluster.| +|[**Kubernetes Cluster Run Command**](/manual/jobs/job-plugins/node-steps/kubernetes-run-command)|Node Step|This plugin allows you to execute a command in a pod within a Kubernetes cluster.| +|[**Kubernetes Cluster Run Script**](/manual/jobs/job-plugins/node-steps/kubernetes-run-script)|Node Step|This plugin executes a script using a predefined container image within a Kubernetes cluster.| +|[**Kubernetes Cluster Update Object**](/manual/jobs/job-plugins/node-steps/kubernetes-update-object)|Node Step|This plugin updates a specified object of a selected kind within a Kubernetes cluster.| + + +
+
+ +:::tip +Click above see the full list of plugins for Kubernetes. +::: + +### Set up the Open Source Kubernetes Plugins + +#### Python Dependencies + +In order to use the Open Source Kubernetes plugins listed in the Summary above, Python must be installed on the Runbook Automation cluster-members or on the [Enterprise Runner](/administration/runner/index.md) - depending on where the connection to Kubernetes will originate. _(These steps are also needed for Commercial versions using the listed Open Source plugins.)_ + +The plugins will work with both **Python 2.7.x** and **Python 3.x.x**. + +Once python is installed, download and install the **`kubernetes`** python client. For **Python 2.7.x** this can be done with **`pip install kubernetes`** and for **Python 3.x.x** this can be done with **`pip3 install kubernetes`**. + +Optionally test that the Kubernetes client has been installed successfully by executing the following at the command-line: **`python`** followed by **`from kubernetes import client, config`**: + +``` +ubuntu@ip-172-31-13-91:~$ python +Python 2.7.17 (default, Mar 8 2023, 18:40:28) +[GCC 7.5.0] on linux2 +Type "help", "copyright", "credits" or "license" for more information. +>>> from kubernetes import client, config +>>> +``` + +#### Kubernetes Authentication for Open Source Plugins + +By default, the Kubernetes plugins look for a Kube Config file at **`$RDECK_BASE/.kube/config`**. For **Deb** and **RPM** this would translate to **`/var/lib/rundeck/.kube/config`**. +The Kube Config file can be saved to a different location, just be sure to take note of where it is saved for later steps. + +If it is preferred to use a Kubernetes API Token, then follow the instructions outlined [here](https://www.cncf.io/blog/2020/07/31/kubernetes-rbac-101-authentication/) to generate the Service Account Token. +Once created, save the Token to [Key Storage](/manual/system-configs.md#key-storage) as a **Password** secret type. + +#### Upload Kubernetes Plugins (Rundeck OSS Only) + +Rundeck OSS does not come preloaded with the Kubernetes plugins. To install the Kubernetes plugins, use the following steps: + +1. Navigate to the [latest plugin release](https://github.com/rundeck-plugins/kubernetes/releases/latest) on Github and download the **`kubernetes-X.X.XX.zip`** file.

+2. In Rundeck, click the **Gear Icon** and then click the **Plugins > Upload Plugin**: + ![Upload Plugins Menu](/assets/img/upload-plugins-menu.png) +3. Click **Browse** and select the downloaded **`.zip`** file from Step 2. +4. Click **Install**: + ![Upload Kubernetes Plugins](/assets/img/upload-k8s-plugins.png) + +### Test Open Source Kubernetes Plugins + +To test that the dependencies and authentication have been configured correctly, use a Kubernetes Node Step plugin - as this will provide the option to easily +execute the plugin in _debug_ mode. + +1. Create a new Job. +2. Navigate to the **Workflow** tab. +3. Click **+ Add a step**. +4. In the **Search step** field type **`Kubernetes`**. +5. Select the **Kubernetes / Pod / Describe** plugin from the list. +6. Type in a pod name into the **Name** field. + ![K8s Describe Pod](/assets/img/k8s-describe-pod.png) +7. Type in the namespace of the pod in the **Namespace** field. +8. If the Kube Config file is saved in the directory **`$RDECK_BASE/.kube/config`** (`/var/lib/rundeck/.kube/config`for RPM and Deb), then the authentication fields can be left blank. + * Otherwise, specify the custom Kube Config location. +9. Optionally chance the **Python Interpreter** if python scripts are not invoked using `python my_script.py` but rather `python2 my_script.py` or `python3 my_script.py`. +10. Click **Save** on the Job Step and then **Save** to save the Job. +11. Click **Run Job Now** to test that the configuration is correct. + +Now that configuration is complete, take a look at use-cases for Runbook Automation with Kubernetes such as +[Capturing Debug Data from Apps in Kubernetes](/learning/solutions/automated-diagnostics/examples/k8s-app-debug-capture) +or [Managing Kubernetes with Rundeck](/learning/howto/how2kube.md#managing-kubernetes-with-rundeck). \ No newline at end of file diff --git a/docs/manual/plugins/kubernetes-plugins-overview.md b/docs/manual/plugins/kubernetes-plugins-overview.md index 81982eb0b..d6ab16fb4 100644 --- a/docs/manual/plugins/kubernetes-plugins-overview.md +++ b/docs/manual/plugins/kubernetes-plugins-overview.md @@ -1,132 +1,138 @@ # Kubernetes Plugins - -## Overview - -![](/assets/img/kubernetes-icon.png) - -Runbook Automation integrates with Kubernetes through a variety of plugins. By integrating Runbook Automation with Kubernetes, users can automate and provide self-service interfaces for operations in their Kubernetes Clusters. These integrations allow operations teams to provide self-service mechanisms to users throughout the business, as well as setup event-driven automation for workflows with Kubernetes. - -
List of Kubernetes Plugins - - -**Available in Rundeck Open Source** - -|Plugin Name| Plugin Type| Description| -|:---------------------------------------------------------|:---------------------------------------------------------:|:---------------------------------------------------------| -|[**Create Deployment**](/manual/jobs/job-plugins/node-steps/kubernetes-deployment-plugins.md#kubernetes-deployment-create)|Node Step|Create a new deployment.| -|[**Delete Deployment**](/manual/jobs/job-plugins/node-steps/kubernetes-deployment-plugins.md#kubernetes-deployment-delete)|Node Step|Delete an existing deployment.| -|[**Deployment Status**](/manual/jobs/job-plugins/node-steps/kubernetes-deployment-plugins.md#kubernetes-deployment-status)|Node Step|Get the status of an existing deployment.| -|[**Update Deployment**](/manual/jobs/job-plugins/node-steps/kubernetes-deployment-plugins.md#kubernetes-deployment-update)|Node Step|Update an existing deployment.| -|[**Waitfor Deployment**](/manual/jobs/job-plugins/node-steps/kubernetes-deployment-plugins.md#kubernetes-deployment-waitfor)|Node Step|Pause workflow until deployment is complete.| -|[**Create Job**](/manual/jobs/job-plugins/node-steps/kubernetes-job-plugins.md#kubernetes-job-create)|Node Step|Create a new Kubernetes job.| -|[**Delete Job**](/manual/jobs/job-plugins/node-steps/kubernetes-job-plugins.md#kubernetes-job-delete)|Node Step|Delete an existing Kubernetes job.| -|[**Re-run Job**](/manual/jobs/job-plugins/node-steps/kubernetes-job-plugins.md#kubernetes-job-re-run)|Node Step|Re-runs an existing Kubernetes job.| -|[**Waitfor Job**](/manual/jobs/job-plugins/node-steps/kubernetes-job-plugins.md#kubernetes-job-waitfor)|Node Step|Pause workflow until Kubernetes job is complete.| -|[**Create Service**](/manual/jobs/job-plugins/node-steps/kubernetes-service-plugins.md#kubernetes-service-create)|Node Step|Create a new Kubernetes service.| -|[**Update Service**](/manual/jobs/job-plugins/node-steps/kubernetes-service-plugins.md#kubernetes-service-update)|Node Step|Update an existing Kubernetes service.| -|[**Delete Service**](/manual/jobs/job-plugins/node-steps/kubernetes-service-plugins.md#kubernetes-service-delete)|Node Step|Delete an existing Kubernetes service.| -|[**Pods Node Source**](/manual/projects/resource-model-sources/kubernetes.md)|Resource Model|Populates node inventory with Kubernetes pods.| -|[**Create Pod**](/manual/jobs/job-plugins/node-steps/kubernetes-pod-plugins.md#kubernetes-pod-create)|Node Step|Create a new Kubernetes pod.| -|[**Delete Pod**](/manual/jobs/job-plugins/node-steps/kubernetes-pod-plugins.md#kubernetes-pod-delete)|Node Step|Delete an existing Kubernetes pod.| -|[**Describe Pod**](/manual/jobs/job-plugins/node-steps/kubernetes-pod-plugins.md#kubernetes-pod-describe)|Node Step|Describe a running Kubernetes pod.| -|[**Execute Command**](/manual/jobs/job-plugins/node-steps/kubernetes-pod-plugins.md#kubernetes-pod-execute-command)|Node Step|Execute a command inside a container in a running pod.| -|[**Execute Script**](/manual/jobs/job-plugins/node-steps/kubernetes-pod-plugins.md#kubernetes-pod-execute-script)|Node Step|Execute a script inside a container in a running pod.| -|[**Pod Logs**](/manual/jobs/job-plugins/node-steps/kubernetes-pod-plugins.md#kubernetes-pod-logs)|Node Step|View the logs of a running pod.| -|[**Waitfor Pod**](/manual/jobs/job-plugins/node-steps/kubernetes-pod-plugins.md#kubernetes-pod-waitfor)|Node Step|Pause workflow until pod is in "ready" state.| -|[**Debug Pod**](/manual/jobs/job-plugins/node-steps/kubernetes-debug-plugins.md#kubernetes-debug-ephemeral-container)|Node Step|Debug a running container inside an existing pod using an ephemeral container.| -|[**Waitfor StatefulSet**](/manual/jobs/job-plugins/node-steps/kubernetes-statefulset-plugins.md#kubernetes-statefulset-waitfor)|Node Step|Pause workflow until StatefulSet has been successfully deployed.| - -**Plugins available only in Commercial products** -> Note: All Open Source plugins also included. - -|Plugin Name| Plugin Type| Description| -|:---------------------------------------------------------|:---------------------------------------------------------:|:---------------------------------------------------------| -|[**Amazon EKS Node Source**](/manual/projects/resource-model-sources/aws-eks.md)|Node Source|Imports Amazon Web Services EKS Clusters as Nodes.| -|[**Azure AKS Node Source**](/manual/projects/resource-model-sources/azure-aks.md)|Node Source|Imports Azure AKS Clusters as Nodes.| -|[**Google Cloud GKE Node Source**](/manual/projects/resource-model-sources/gcp-gke.md)|Node Source|Imports Google Cloud GKE Clusters as Nodes.| -|[**Kubernetes Cluster Create Object**](/manual/jobs/job-plugins/node-steps/kubernetes-create-object)|Node Step|This plugin creates an object of a selected kind within a Kubernetes cluster.| -|[**Kubernetes Cluster Delete Object**](/manual/jobs/job-plugins/node-steps/kubernetes-delete-object)|Node Step|This plugin deletes an object of a selected kind within a Kubernetes cluster.| -|[**Kubernetes Cluster Describe Object**](/manual/jobs/job-plugins/node-steps/kubernetes-describe-object)|Node Step|This plugin describes an object of a selected kind within a Kubernetes cluster.| -|[**Kubernetes Cluster List Objects**](/manual/jobs/job-plugins/node-steps/kubernetes-list-objects)|Node Step|This plugin lists objects of a selected kind within a Kubernetes cluster.| -|[**Kubernetes Cluster Object Logs**](/manual/jobs/job-plugins/node-steps/kubernetes-object-logs)|This plugin allows you to view the logs of an object within a Kubernetes cluster.| -|[**Kubernetes Cluster Run Command**](/manual/jobs/job-plugins/node-steps/kubernetes-run-command)|Node Step|This plugin allows you to execute a command in a pod within a Kubernetes cluster.| -|[**Kubernetes Cluster Run Script**](/manual/jobs/job-plugins/node-steps/kubernetes-run-script)|Node Step|This plugin executes a script using a predefined container image within a Kubernetes cluster.| -|[**Kubernetes Cluster Update Object**](/manual/jobs/job-plugins/node-steps/kubernetes-update-object)|Node Step|This plugin updates a specified object of a selected kind within a Kubernetes cluster.| - - -
-
- -:::tip -Click above see the full list of plugins for Kubernetes. +:::enterprise ::: +![](/assets/img/kubernetes-icon.png) -## Setup the Open Source Kubernetes Plugins - -### Python Dependencies - -In order to use the Open Source Kubernetes plugins listed in the Summary above, Python must be installed on the Runbook Automation cluster-members or on the [Enterprise Runner](/administration/runner/index.md) - depending on where the connection to Kubernetes will originate. _(These steps are also needed for Commercial versions using the listed Open Source plugins.)_ - -The plugins will work with both **Python 2.7.x** and **Python 3.x.x**. - -Once python is installed, download and install the **`kubernetes`** python client. For **Python 2.7.x** this can be done with **`pip install kubernetes`** and for **Python 3.x.x** this can be done with **`pip3 install kubernetes`**. - -Optionally test that the Kubernetes client has been installed successfully by executing the following at the command-line: **`python`** followed by **`from kubernetes import client, config`**: - -``` -ubuntu@ip-172-31-13-91:~$ python -Python 2.7.17 (default, Mar 8 2023, 18:40:28) -[GCC 7.5.0] on linux2 -Type "help", "copyright", "credits" or "license" for more information. ->>> from kubernetes import client, config ->>> -``` - -### Kubernetes Authentication - -By default, the Kubernetes plugins look for a Kube Config file at **`$RDECK_BASE/.kube/config`**. For **Deb** and **RPM** this would translate to **`/var/lib/rundeck/.kube/config`**. -The Kube Config file can be saved to a different location, just be sure to take note of where it is saved for later steps. - -If it is preferred to use a Kubernetes API Token, then follow the instructions outlined [here](https://www.cncf.io/blog/2020/07/31/kubernetes-rbac-101-authentication/) to generate the Service Account Token. -Once created, save the Token to [Key Storage](/manual/system-configs.md#key-storage) as a **Password** secret type. - -### Upload Kubernetes Plugins (Rundeck OSS Only) - -Rundeck OSS does not come preloaded with the Kubernetes plugins. To install the Kubernetes plugins, use the following steps: - -1. Navigate to the [latest plugin release](https://github.com/rundeck-plugins/kubernetes/releases/latest) on Github and download the **`kubernetes-X.X.XX.zip`** file.

-2. In Rundeck, click the **Gear Icon** and then click the **Plugins > Upload Plugin**: - ![Upload Plugins Menu](/assets/img/upload-plugins-menu.png) -3. Click **Browse** and select the downloaded **`.zip`** file from Step 2. -4. Click **Install**: - ![Upload Kubernetes Plugins](/assets/img/upload-k8s-plugins.png) - -## Test Kubernetes Plugins +Runbook Automation integrates with Kubernetes through a variety of plugins. By integrating Runbook Automation with Kubernetes, users can automate and provide self-service interfaces for operations in their Kubernetes Clusters. -To test that the dependencies and authentication have been configured correctly, use a Kubernetes Node Step plugin - as this will provide the option to easily -execute the plugin in _debug_ mode. +:::warning Open Source Plugins +This document covers the plugins available in the commercial Runbook Automation products. For a list of Kubernetes plugins available for Rundeck Community (open-source), see documentation for the [**Open Source Kubernetes plugins**](/manual/plugins/kubernetes-open-source.md). +::: -1. Create a new Job. -2. Navigate to the **Workflow** tab. -3. Click **+ Add a step**. -4. In the **Search step** field type **`Kubernetes`**. -5. Select the **Kubernetes / Pod / Describe** plugin from the list. -6. Type in a pod name into the **Name** field. -![K8s Describe Pod](/assets/img/k8s-describe-pod.png) -7. Type in the namespace of the pod in the **Namespace** field. -8. If the Kube Config file is saved in the directory **`$RDECK_BASE/.kube/config`** (`/var/lib/rundeck/.kube/config`for RPM and Deb), then the authentication fields can be left blank. - * Otherwise, specify the custom Kube Config location. -9. Optionally chance the **Python Interpreter** if python scripts are not invoked using `python my_script.py` but rather `python2 my_script.py` or `python3 my_script.py`. -10. Click **Save** on the Job Step and then **Save** to save the Job. -11. Click **Run Job Now** to test that the configuration is correct. +## Kubernetes Plugins in Runbook Automation -Now that configuration is complete, take a look at use-cases for Runbook Automation with Kubernetes such as -[Capturing Debug Data from Apps in Kubernetes](/learning/solutions/automated-diagnostics/examples/k8s-app-debug-capture) -or [Managing Kubernetes with Rundeck](/learning/howto/how2kube.md#managing-kubernetes-with-rundeck). +### Cluster Discovery & Authentication Options +There are multiple methods for adding Kubernetes clusters to Runbook Automation and authenticating with the Kubernetes API: +1. [**Pod-based Service Account**](#pod-based-service-account): Install a Runner in each cluster (or namespace), and target the Runner as the cluster or particular namespace. The Runner uses the Service Account of the pod that it is hosted in to authenticate with the Kubernetes API. +2. [**Cloud Provider Integration**](#cloud-provider-integration): Use the cloud provider's API to dynamically retrieve all clusters and add them as nodes to the inventory. The cloud provider's API can also optionally be used to retrieve the necessary Kubernetes authentication to communicate with the clusters. +3. [**Manual Authentication Configuration**](#manual-authentication-configuration): Clusters are added to the inventory either manually or through method 1 or 2. The Kubernetes API Token or Kube Config file is manually added to Key Storage and configured as node-attributes. +:::tip Prerequisite Configuration +Note that all of these methods require the use of the **Automatic** mode for the Project's use of Runners. See [this documentation](/administration/runner/runner-management/project-dispatch-configuration.md) to confirm that your project is configured correctly. +::: +### Pod-based Service Account + +With this method, clusters are added to the inventory by installing a Runner in the cluster and adding the Runner as a node to the inventory. The Runner uses the Service Account of the pod that it is hosted in to authenticate with the Kubernetes API. + +This method is recommended if you want to have a 1:1 relationship between Runners and Kubernetes clusters or between Runners and namespaces within clusters, or if you are unable to use the Cloud Provider Integration method outlined in the next section. + +Follow these steps to set up a Runner in a Kubernetes cluster: + +1. Create a new Runner within your Project using the API. Replace **`URL`** with your Runbook Automation instance URL, **`PROJECT`** with the project name, and **`API_TOKEN`** with your API Token: + ```bash + curl --location --request POST 'https://[URL]/api/42/project/[PROJECT]/runnerManagement/runners' \ + --header 'Accept: application/json' \ + --header 'X-Rundeck-Auth-Token: [API_TOKEN]' \ + --header 'Content-Type: application/json' \ + --data-raw '{ + "name": "K8s Runner US-WEST-1 Cluster 1", + "description": "Runner installed in US-WEST-1 Cluster 1", + "tagNames": ["K8S-RUNNER", "us-west-1", "cluster-1"] + }' + ``` + :::tip Tip + It is recommended to add at least one **Tag** through the `tagNames` field to the Runner, as this simplifies adding the Node Enhancer in step 4. + ::: + The response will provide the following. Be sure to capture the **`runnerId`** and the **`token`**: + ``` + {"description":"Runner installed in US-WEST-1 Cluster 1", + "downloadTk":"fbc12393-3454-426d-9dd0-6e72ce53b9d5", + "name":"K8s Runner","projectAssociations":{"network-infra":".*"}, + "runnerId":"acc00df8-fbb8-497a-8f7f-07eaaa0c5b78","token":"6Y4bHjk4TCU1MUGBaso9Ak7sHOokwRkw"} + ``` +2. Create a deployment YAML for the Runner. Be sure to replace **`[namespace]`**, **`[runnerId]`** with the value from the previous step, **`[token]`**, and **`[Runbook Automation Instance URL]`**: + ``` + apiVersion: v1 + kind: Pod + metadata: + namespace: [namespace] + name: rundeck-runner + labels: + app: rundeck-runner + spec: + containers: + - image: rundeckpro/runner + imagePullPolicy: IfNotPresent + name: rundeck-runner + env: + - name: RUNNER_RUNDECK_CLIENT_ID + value: "[runnerId]" + - name: RUNNER_RUNDECK_SERVER_TOKEN + value: "[token]" + - name: RUNNER_RUNDECK_SERVER_URL + value: "https://[Runbook Automation Instance URL]" + lifecycle: + postStart: + exec: + command: + - /bin/sh + - -c + - touch this_is_from_rundeck_runner + restartPolicy: Always + ``` +3. Create the deployment: **`kubectl apply -f deployment.yml`**. +4. Add a Node Attribute to the Runner's node in the inventory through an [**Attribute Match Node Enhancer**](/manual/node-enhancers.md#attribute-match). + - Set the **Attribute Match** to use one of the tags set in **Step 1**: **`tags=~.*K8S-RUNNER.*`** + - Set the **Attributes to Add** as: **`kubernetes-use-pod-service-account=true`** + :::tip Tip + This step is only required one time if you use the same tag for all Runners that are deployed into Kubernetes clusters and use the Pod-based Service Account method. + ::: + +The Runner will now be able to authenticate with the Kubernetes API using the Service Account of the pod that it is hosted in. + +### Cloud Provider Integration + +The Cloud Provider Integration method can be used to dynamically retrieve all clusters from the cloud provider's API and add them as nodes to the inventory. +The cloud provider's API can _also_ be used to retrieve the necessary Kubernetes authentication to communicate with the clusters. + +#### Cloud Provider for Cluster Discovery + +Use the Node Source plugins for the cloud provider to add the clusters to the Node Inventory: + +- [**Amazon EKS Node Source**](/manual/projects/resource-model-sources/aws-eks.md) +- [**Azure AKS Node Source**](/manual/projects/resource-model-sources/azure-aks.md) +- [**Google Cloud GKE Node Source**](/manual/projects/resource-model-sources/gcp-gke.md) + +Note that a Runner does _not_ need to be installed to configure these Node Source plugins. + +#### Cloud Provider for Kubernetes Authentication + +The Cloud Provider Integration method can also be used to retrieve the necessary Kubernetes authentication to communicate with the clusters. +This is useful when there are multiple clusters and you wish to have a single Runner that can communicate with all of them. + +Follow the instructions in the **Node Source Plugins** linked in the prior sections to use the Cloud Provider Integration method. + +:::tip Cloud Provider for Discovery and Pod Service Account for Authentication +It is possible to use the Cloud Provider Integration method for cluster discovery and the Pod-based Service Account method for authentication. This is useful when you want to dynamically discover clusters but have a 1:1 relationship between Runners and clusters or do not have the option to use the cloud provider for retrieving cluster credentials. +To take this approach, be sure to select the **Use Pod Service Account for Node Steps** when configuring the Node Source plugins. +::: +### Manual Authentication Configuration +If you do not have the option to place the Runner inside the target cluster or use the Cloud Provider Integration method, you can manually configure the Kubernetes authentication. +1. Create an API token for a service account following the steps outlined [here](https://kubernetes.io/docs/tasks/configure-pod-container/configure-service-account/#manually-create-a-long-lived-api-token-for-a-serviceaccount). +2. Retrieve the `token` and the `ca.crt` from the secret created in the previous step: **`kubectl get secret/[secret-name] -o yaml`**. +3. Add both the `token` and the `ca.crt` to Key Storage. +4. Next, retrieve the cluster's API endpoint. This can be found by running **`kubectl cluster-info`**. +5. Add a node to the inventory and add the following as node attributes: + ``` + kubernetes-cloud-provider=self-hosted + kubernetes-cluster-endpoint=<> + kubernetes-token-path=<> + kubernetes-ca-cert-path=<> + ``` +This node can now be targeted by the Kubernetes node-step plugins. \ No newline at end of file