From ad94cae7f9e54a2c4b2dce0614a41ce14dd59320 Mon Sep 17 00:00:00 2001 From: Yingrong Zhao Date: Mon, 6 Feb 2023 10:57:42 -0500 Subject: [PATCH 1/3] add administrators doc for configre porter agent Signed-off-by: Yingrong Zhao --- .../administrators/configure-porter-agent.md | 76 +++++++++++++++++++ 1 file changed, 76 insertions(+) create mode 100644 docs/content/administrators/configure-porter-agent.md diff --git a/docs/content/administrators/configure-porter-agent.md b/docs/content/administrators/configure-porter-agent.md new file mode 100644 index 00000000..46f082cf --- /dev/null +++ b/docs/content/administrators/configure-porter-agent.md @@ -0,0 +1,76 @@ +--- +title: Configuring the Porter Agent +description: How to customize Porter Agent +--- + +The Porter Agent is a critical component in executing Porter commands in a controlled and reliable manner. With the AgentConfig Custom Resource Definition (CRD), you can customize the Porter Agent to meet your specific needs and requirements. + +This guide will show some ways to configure the Porter Agent through the [AgentConfig CRD](/operator/file-format/#agentconfig). + +First, let's create a new file with the AgentConfig CRD: +```yaml +apiVersion: getporter.org/v1 +kind: AgentConfig +metadata: + name: customAgent +spec: +``` + +### Specifying a version + +By default, the Porter Agent uses the latest version from the official GitHub release. However, if you want to use a different version or a custom build hosted outside the official project, you can specify the repository and the version in the CRD. Here's an example: +```yaml +apiVersion: getporter.org/v1 +kind: AgentConfig +metadata: + name: customAgent +spec: + porterRepository: + porterVersion: v1.2.3 +``` + +### Configuring Access Permission + +In some cases, you may want to restrict access to the private registry that contains the images you need to install. With the AgentConfig CRD, you can specify two service accounts, one for the pod that runs the Agent job and another for the pod that runs the Porter installation. Here's an example: +```yaml +apiVersion: getporter.org/v1 +kind: AgentConfig +metadata: + name: customAgent +spec: + porterRepository: + porterVersion: v1.2.3 + serviceAccount: + installationServiceAccount: +``` + +For more information on working with private registry images, see [this section of the Porter Operator Quickstart Guide](/quickstart/#private-bundle-registries). + + + +## Configuring Porter Plugins + +In addition to specifying the version of Porter, you can also specify the plugins you need to install before bundle executions. For example, if you want to use the Kubernetes and Azure plugins, you can configure the AgentConfig like this: +```yaml +apiVersion: getporter.org/v1 +kind: AgentConfig +metadata: + name: customAgent +spec: + porterRepository: + porterVersion: v1.2.3 + pluginConfigFile: + schemaVersion: 1.0.0 + plugins: + kubernetes: + version: v1.0.1 + azure: + version: v1.0.1 + +``` + +The schema for the pluginConfigFile field is defined [in the Porter reference documentation](/reference/file-formats/#plugins). + +🚨 WARNING: By default, the plugin version is set to `latest`. However, it is recommended to specify the plugin version to avoid any unexpected behavior that could result from an outdated plugin. + + From 93ce0ff655b57e385a034c96aa076ddbac5bbdd1 Mon Sep 17 00:00:00 2001 From: Yingrong Zhao Date: Tue, 7 Feb 2023 11:50:31 -0500 Subject: [PATCH 2/3] address comments Signed-off-by: Yingrong Zhao --- .../administrators/configure-porter-agent.md | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/docs/content/administrators/configure-porter-agent.md b/docs/content/administrators/configure-porter-agent.md index 46f082cf..4ee8f990 100644 --- a/docs/content/administrators/configure-porter-agent.md +++ b/docs/content/administrators/configure-porter-agent.md @@ -3,7 +3,7 @@ title: Configuring the Porter Agent description: How to customize Porter Agent --- -The Porter Agent is a critical component in executing Porter commands in a controlled and reliable manner. With the AgentConfig Custom Resource Definition (CRD), you can customize the Porter Agent to meet your specific needs and requirements. +The Porter Agent is a containerized version of the Porter CLI that is optimized for running Porter commands on a Kubernetes cluster. With the AgentConfig Custom Resource Definition (CRD), you can customize how the Porter Agent is run to meet your specific needs and requirements. For example, you can specify the version of Porter to use, install additional Porter plugins, or provide a custom Porter config file. This guide will show some ways to configure the Porter Agent through the [AgentConfig CRD](/operator/file-format/#agentconfig). @@ -44,21 +44,22 @@ spec: installationServiceAccount: ``` +The porter operator ships two pre-defined ClusterRole, editor role and viewer role, for AgentConfig resources to help you to properly assign permissions to a custom service account. + For more information on working with private registry images, see [this section of the Porter Operator Quickstart Guide](/quickstart/#private-bundle-registries). ## Configuring Porter Plugins -In addition to specifying the version of Porter, you can also specify the plugins you need to install before bundle executions. For example, if you want to use the Kubernetes and Azure plugins, you can configure the AgentConfig like this: +You can also specify any required plugins necessary for your installation of Porter. For example, if you want to use the Kubernetes and Azure plugins, you can configure the AgentConfig like this: + ```yaml apiVersion: getporter.org/v1 kind: AgentConfig metadata: name: customAgent spec: - porterRepository: - porterVersion: v1.2.3 pluginConfigFile: schemaVersion: 1.0.0 plugins: @@ -71,6 +72,4 @@ spec: The schema for the pluginConfigFile field is defined [in the Porter reference documentation](/reference/file-formats/#plugins). -🚨 WARNING: By default, the plugin version is set to `latest`. However, it is recommended to specify the plugin version to avoid any unexpected behavior that could result from an outdated plugin. - - +🚨 WARNING: By default, the plugin version is set to `latest`. We recommend pinning to specific version of any plugins used to avoid undesired behavior caused by a stale plugin cache. Porter currently does not expire cached installations of plugins, so installing "latest" will not pick up new versions of plugins when they are released. \ No newline at end of file From 4732b3924491c6bb24c81f93f0528ceaa56ab083 Mon Sep 17 00:00:00 2001 From: Yingrong Zhao Date: Tue, 7 Feb 2023 15:23:18 -0500 Subject: [PATCH 3/3] address comments Signed-off-by: Yingrong Zhao --- docs/content/administrators/configure-porter-agent.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/content/administrators/configure-porter-agent.md b/docs/content/administrators/configure-porter-agent.md index 4ee8f990..71e4bade 100644 --- a/docs/content/administrators/configure-porter-agent.md +++ b/docs/content/administrators/configure-porter-agent.md @@ -44,7 +44,7 @@ spec: installationServiceAccount: ``` -The porter operator ships two pre-defined ClusterRole, editor role and viewer role, for AgentConfig resources to help you to properly assign permissions to a custom service account. +The porter operator ships two pre-defined ClusterRole, agentconfigs-editor-role and agentconfigs-viewer-role, for AgentConfig resources to help you to properly assign permissions to a custom service account. For more information on working with private registry images, see [this section of the Porter Operator Quickstart Guide](/quickstart/#private-bundle-registries).