From 212c6cc40385948b30ca25cd30f23faaae919b7e Mon Sep 17 00:00:00 2001 From: Andrew Lavery Date: Wed, 18 Jun 2025 14:44:47 -0400 Subject: [PATCH 1/9] expand the required set of permissions for minimal RBAC --- docs/vendor/replicated-sdk-customizing.md | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/docs/vendor/replicated-sdk-customizing.md b/docs/vendor/replicated-sdk-customizing.md index bf470cce6d..1abc2eac96 100644 --- a/docs/vendor/replicated-sdk-customizing.md +++ b/docs/vendor/replicated-sdk-customizing.md @@ -50,10 +50,13 @@ rules: The SDK requires the following minimum RBAC permissions: * Create Secrets. -* Get and update Secrets named `replicated`, `replicated-instance-report`, and `replicated-custom-app-metrics-report`. +* Get and update Secrets named `replicated`, `replicated-instance-report`, `replicated-meta-data`, and `replicated-custom-app-metrics-report`. +* Get the `replicated` deployment. +* Get the `replicaset` and `pods` corresponding to the `replicated` deployment. * The SDK requires the following minimum RBAC permissions for status informers: - * If you defined custom status informers, then the SDK must have permissions to get, list, and watch all the resources listed in the `replicated.statusInformers` array in your Helm chart `values.yaml` file. - * If you did _not_ define custom status informers, then the SDK must have permissions to get, list, and watch the following resources: + * If you defined custom status informers, then the SDK must have permissions to `list` and `watch` all the types of resources listed in the `replicated.statusInformers` array in your Helm chart `values.yaml` file, as well as the ability to `get` the named resource. + * For instance, if you have a single status informer `deployment/myapp`, then the SDK requires permissions to `list` and `watch` all deployments as well as `get` the `myapp` deployment. + * If you did _not_ define custom status informers, then the SDK must have permissions to `get`, `list`, and `watch` the following resources: * Deployments * Daemonsets * Ingresses From 2ada912b3c7967676ddf68a01f07c46590754ed9 Mon Sep 17 00:00:00 2001 From: Andrew Lavery Date: Wed, 18 Jun 2025 19:05:02 -0400 Subject: [PATCH 2/9] add minimal RBAC example with statusInformer --- docs/vendor/replicated-sdk-customizing.md | 121 +++++++++++++++++++++- 1 file changed, 120 insertions(+), 1 deletion(-) diff --git a/docs/vendor/replicated-sdk-customizing.md b/docs/vendor/replicated-sdk-customizing.md index 1abc2eac96..b102251001 100644 --- a/docs/vendor/replicated-sdk-customizing.md +++ b/docs/vendor/replicated-sdk-customizing.md @@ -10,7 +10,7 @@ This section describes role-based access control (RBAC) for the Replicated SDK, ### Default RBAC -The SDK creates default Role, RoleBinding, and ServiceAccount objects during installation. The default Role allows the SDK to get, list, and watch all resources in the namespace, to create Secrets, and to update the `replicated` and `replicated-instance-report` Secrets: +The SDK creates default Role, RoleBinding, and ServiceAccount objects during installation. The default Role allows the SDK to get, list, and watch all resources in the namespace, to create Secrets, and to update the `replicated`, `replicated-instance-report`, `replicated-custom-app-metrics-report`, and `replicated-meta-data` Secrets: ```yaml apiVersion: rbac.authorization.k8s.io/v1 @@ -44,6 +44,7 @@ rules: - replicated - replicated-instance-report - replicated-custom-app-metrics-report + - replicated-meta-data ``` ### Minimum RBAC Requirements @@ -269,3 +270,121 @@ This is the format produced by `kubectl create secret tls --cert=< tlsCertSecretName: YOUR_TLS_SECRET ``` Where `YOUR_TLS_SECRET` is the secret in the namespace containing the TLS certificate and key. + +## Minimal RBAC + +With the Replicated SDK version 1.7.0 and later, you can enable the use of a less-permissive RBAC role for the SDK pod by setting the `replicated.minimalRBAC` Helm value in your Helm chart. + +```yaml +# Helm chart values.yaml + +replicated: + minimalRBAC: true +``` + +If statusInformers are not set manually, this RBAC role will include permissions to `get`, `list`, and `watch` all secrets, deployments, statefulsets, daemonsets, services, ingresses, PVCs, pods, replicasets, and endpoints within the namespace. +This allows Replicated to discover the Helm chart secret for your application, parse it to determine what resources to monitor, and then monitor those resources. + +If statusInformers are set manually, then the generated role will not be created with the ability to access all secrets, and other resources will be specified by name when possible. +An example statusInformer configuration and generated role is presented below. + +```yaml +# Helm chart values.yaml + +replicated: + minimalRBAC: true + statusInformers: + - deployment/replicated + - deployment/myapp + - service/replicated + - service/myapp +``` + +```yaml +# Generated RBAC role + +apiVersion: rbac.authorization.k8s.io/v1 +kind: Role +metadata: + name: replicated-role +rules: +- apiGroups: + - "" + resources: + - secrets + verbs: + - create +- apiGroups: + - "" + resourceNames: + - replicated + - replicated-instance-report + - replicated-custom-app-metrics-report + - replicated-meta-data + resources: + - secrets + verbs: + - update +- apiGroups: + - apps + resourceNames: + - replicated + resources: + - deployments + verbs: + - get +- apiGroups: + - apps + resources: + - replicasets + verbs: + - get +- apiGroups: + - "" + resources: + - pods + verbs: + - get +- apiGroups: + - "" + resourceNames: + - replicated + resources: + - secrets + verbs: + - get +- apiGroups: + - apps + resources: + - deployments + verbs: + - list + - watch +- apiGroups: + - apps + resourceNames: + - replicated + - myapp + resources: + - deployments + verbs: + - get +- apiGroups: + - "" + resources: + - services + - endpoints + verbs: + - list + - watch +- apiGroups: + - "" + resourceNames: + - replicated + - myapp + resources: + - services + - endpoints + verbs: + - get +``` From f98067370ca5220fb39b5d8e6d70b588b7a7de08 Mon Sep 17 00:00:00 2001 From: Andrew Lavery Date: Wed, 18 Jun 2025 19:08:27 -0400 Subject: [PATCH 3/9] add no statusInformer minimal RBAC example --- docs/vendor/replicated-sdk-customizing.md | 99 ++++++++++++++++++++++- 1 file changed, 98 insertions(+), 1 deletion(-) diff --git a/docs/vendor/replicated-sdk-customizing.md b/docs/vendor/replicated-sdk-customizing.md index b102251001..7a5e2ab295 100644 --- a/docs/vendor/replicated-sdk-customizing.md +++ b/docs/vendor/replicated-sdk-customizing.md @@ -285,6 +285,103 @@ replicated: If statusInformers are not set manually, this RBAC role will include permissions to `get`, `list`, and `watch` all secrets, deployments, statefulsets, daemonsets, services, ingresses, PVCs, pods, replicasets, and endpoints within the namespace. This allows Replicated to discover the Helm chart secret for your application, parse it to determine what resources to monitor, and then monitor those resources. +```yaml +# Generated RBAC role with no statusInformers + +apiVersion: rbac.authorization.k8s.io/v1 +kind: Role +metadata: + name: replicated-role +rules: +- apiGroups: + - "" + resources: + - secrets + verbs: + - create +- apiGroups: + - "" + resourceNames: + - replicated + - replicated-instance-report + - replicated-custom-app-metrics-report + - replicated-meta-data + resources: + - secrets + verbs: + - update +- apiGroups: + - apps + resourceNames: + - replicated + resources: + - deployments + verbs: + - get +- apiGroups: + - apps + resources: + - replicasets + verbs: + - get +- apiGroups: + - "" + resources: + - pods + verbs: + - get +- apiGroups: + - "" + resourceNames: + - replicated + resources: + - secrets + verbs: + - get +- apiGroups: + - "" + resources: + - secrets + verbs: + - get + - list +- apiGroups: + - apps + resources: + - deployments + - replicasets + - statefulsets + - daemonsets + verbs: + - get + - list + - watch +- apiGroups: + - "" + resources: + - services + - endpoints + - persistentvolumeclaims + verbs: + - get + - list + - watch +- apiGroups: + - networking.k8s.io + resources: + - ingresses + verbs: + - get + - list + - watch +- apiGroups: + - "" + resources: + - pods + verbs: + - list +``` + If statusInformers are set manually, then the generated role will not be created with the ability to access all secrets, and other resources will be specified by name when possible. An example statusInformer configuration and generated role is presented below. @@ -301,7 +398,7 @@ replicated: ``` ```yaml -# Generated RBAC role +# Generated RBAC role with deployment/replicated, deployment/myapp, service/replicated and service/myapp statusinformers apiVersion: rbac.authorization.k8s.io/v1 kind: Role From a1605912cbeca249018ad9e45e855109e31e9599 Mon Sep 17 00:00:00 2001 From: Paige Calvert Date: Fri, 20 Jun 2025 09:28:31 -0600 Subject: [PATCH 4/9] minor formatting edit --- docs/vendor/replicated-sdk-customizing.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/vendor/replicated-sdk-customizing.md b/docs/vendor/replicated-sdk-customizing.md index 7a5e2ab295..6211f5f01d 100644 --- a/docs/vendor/replicated-sdk-customizing.md +++ b/docs/vendor/replicated-sdk-customizing.md @@ -56,7 +56,8 @@ The SDK requires the following minimum RBAC permissions: * Get the `replicaset` and `pods` corresponding to the `replicated` deployment. * The SDK requires the following minimum RBAC permissions for status informers: * If you defined custom status informers, then the SDK must have permissions to `list` and `watch` all the types of resources listed in the `replicated.statusInformers` array in your Helm chart `values.yaml` file, as well as the ability to `get` the named resource. - * For instance, if you have a single status informer `deployment/myapp`, then the SDK requires permissions to `list` and `watch` all deployments as well as `get` the `myapp` deployment. + + For instance, if you have a single status informer `deployment/myapp`, then the SDK requires permissions to `list` and `watch` all deployments as well as `get` the `myapp` deployment. * If you did _not_ define custom status informers, then the SDK must have permissions to `get`, `list`, and `watch` the following resources: * Deployments * Daemonsets From 9ce7c4ead4e8da1c25cabb64d5b4089137edd915 Mon Sep 17 00:00:00 2001 From: Paige Calvert Date: Fri, 20 Jun 2025 13:09:15 -0600 Subject: [PATCH 5/9] docs edits wip --- docs/vendor/replicated-sdk-customizing.md | 503 ++++++++++++---------- 1 file changed, 274 insertions(+), 229 deletions(-) diff --git a/docs/vendor/replicated-sdk-customizing.md b/docs/vendor/replicated-sdk-customizing.md index 6211f5f01d..3aa6a9a045 100644 --- a/docs/vendor/replicated-sdk-customizing.md +++ b/docs/vendor/replicated-sdk-customizing.md @@ -8,7 +8,262 @@ For information about how to use a custom domain for the Replicated SDK image, s This section describes role-based access control (RBAC) for the Replicated SDK, including the default RBAC, minimum RBAC requirements, and how to install the SDK with custom RBAC. -### Default RBAC +It also describes how to enable the `replicated.minimalRBAC` field to use a less-permissive default RBAC role for the Replicated SDK 1.7.0 and later. + +### Enable `minimalRBAC` + +With the Replicated SDK version 1.7.0 and later, you can enable the use of a less-permissive RBAC role for the SDK pod by setting the `replicated.minimalRBAC` Helm value in your Helm chart, as shown below: + +```yaml +# Helm chart values.yaml + +replicated: + minimalRBAC: true +``` + +For more information about the default RBAC role that is created when `minimalRBAC` is enabled, see [Default RBAC (`minimalRBAC: true`)](#default-rbac-true). + +### Default RBAC (`minimalRBAC: true`) {#default-rbac-true} + +This section describes the default RBAC role that is created for the Replicated SDK when the `replicated.minimalRBAC` field is true. For the default RBAC when `minimalRBAC` is false, see [Default RBAC (`minimalRBAC: false`)](#default-rbac-false). + +The permissions included in the default `minimalRBAC` Role vary depending on if you defined custom _status informers_ for your application. See one of the following sections for more information: +* [Default `minimalRBAC` Role Without Custom Status Informers](#default-no-status-informers) +* [Default `minimalRBAC` Role With Custom Status Informers](#default-status-informers) + +
+ What are status informers? + + The Replicated Vendor Portal uses status informers to provide application status data. For more information about status informers, see [Helm Installations](/vendor/insights-app-status#helm-installations) in _Enabling and Understanding Application Status_. +
+ +#### Default `minimalRBAC` Role Without Custom Status Informers {#default-no-status-informers} + +If you did _not_ define custom status informers for your application, then the default `minimalRBAC` Role includes permissions for the SDK to `get`, `list`, and `watch` the following resources in the namespace: +* Secrets +* Deployments +* StatefulSets +* DaemonSets +* Services +* Ingresses +* PVCs +* Pods +* ReplicaSets +* Endpoints + +These permissions allow the SDK to discover the Helm chart secret for your application, parse it to determine what resources to monitor, and then monitor those resources. + +The following shows the default RBAC role for the SDK when `minimalRBAC` is enabled and no customer status informers are defined: + +```yaml +# Generated RBAC role with no statusInformers + +apiVersion: rbac.authorization.k8s.io/v1 +kind: Role +metadata: + name: replicated-role +rules: +- apiGroups: + - "" + resources: + - secrets + verbs: + - create +- apiGroups: + - "" + resourceNames: + - replicated + - replicated-instance-report + - replicated-custom-app-metrics-report + - replicated-meta-data + resources: + - secrets + verbs: + - update +- apiGroups: + - apps + resourceNames: + - replicated + resources: + - deployments + verbs: + - get +- apiGroups: + - apps + resources: + - replicasets + verbs: + - get +- apiGroups: + - "" + resources: + - pods + verbs: + - get +- apiGroups: + - "" + resourceNames: + - replicated + resources: + - secrets + verbs: + - get +- apiGroups: + - "" + resources: + - secrets + verbs: + - get + - list +- apiGroups: + - apps + resources: + - deployments + - replicasets + - statefulsets + - daemonsets + verbs: + - get + - list + - watch +- apiGroups: + - "" + resources: + - services + - endpoints + - persistentvolumeclaims + verbs: + - get + - list + - watch +- apiGroups: + - networking.k8s.io + resources: + - ingresses + verbs: + - get + - list + - watch +- apiGroups: + - "" + resources: + - pods + verbs: + - list +``` + +#### Default `minimalRBAC` Role With Custom Status Informers {#default-status-informers} + +If you defined custom status informers for your application, then the default `minimalRBAC` role includes permissions only for the specific resources that you defined as status informers. These resources are specified by name when possible. + +For example, the following custom `statusInformer` configuration defines specific Deployment and Service resources as status informers for the application: + +```yaml +# Helm chart values.yaml + +replicated: + minimalRBAC: true + statusInformers: + - deployment/replicated + - deployment/myapp + - service/replicated + - service/myapp +``` + +Given the custom `statusInformer` configuration above, the following `minimalRBAC` role is created: + +```yaml +# Generated RBAC role with deployment/replicated, deployment/myapp, service/replicated and service/myapp statusinformers + +apiVersion: rbac.authorization.k8s.io/v1 +kind: Role +metadata: + name: replicated-role +rules: +- apiGroups: + - "" + resources: + - secrets + verbs: + - create +- apiGroups: + - "" + resourceNames: + - replicated + - replicated-instance-report + - replicated-custom-app-metrics-report + - replicated-meta-data + resources: + - secrets + verbs: + - update +- apiGroups: + - apps + resourceNames: + - replicated + resources: + - deployments + verbs: + - get +- apiGroups: + - apps + resources: + - replicasets + verbs: + - get +- apiGroups: + - "" + resources: + - pods + verbs: + - get +- apiGroups: + - "" + resourceNames: + - replicated + resources: + - secrets + verbs: + - get +- apiGroups: + - apps + resources: + - deployments + verbs: + - list + - watch +- apiGroups: + - apps + resourceNames: + - replicated + - myapp + resources: + - deployments + verbs: + - get +- apiGroups: + - "" + resources: + - services + - endpoints + verbs: + - list + - watch +- apiGroups: + - "" + resourceNames: + - replicated + - myapp + resources: + - services + - endpoints + verbs: + - get +``` + +### Default RBAC (`minimalRBAC: false`) {#default-rbac-false} + +This section describes the default RBAC role that is created for the Replicated SDK when the `replicated.minimalRBAC` field is false. The SDK creates default Role, RoleBinding, and ServiceAccount objects during installation. The default Role allows the SDK to get, list, and watch all resources in the namespace, to create Secrets, and to update the `replicated`, `replicated-instance-report`, `replicated-custom-app-metrics-report`, and `replicated-meta-data` Secrets: @@ -49,6 +304,8 @@ rules: ### Minimum RBAC Requirements +This section describes the minimum RBAC permissions required by the Replicated SDK. Any custom RBAC role that you create must include these permissions at minimum. + The SDK requires the following minimum RBAC permissions: * Create Secrets. * Get and update Secrets named `replicated`, `replicated-instance-report`, `replicated-meta-data`, and `replicated-custom-app-metrics-report`. @@ -70,9 +327,12 @@ The SDK requires the following minimum RBAC permissions: * For any Service resources used as status informers, the SDK requires `get` permissions for Endpoint resources with the same name as the service. The Replicated Vendor Portal uses status informers to provide application status data. For more information, see [Helm Installations](/vendor/insights-app-status#helm-installations) in _Enabling and Understanding Application Status_. + ### Install the SDK with Custom RBAC -#### Custom ServiceAccount +This section describes how to install the SDK with custom RBAC permissions. To install with custom RBAC, you can use a custom ServiceAccount or a custom ClusterRole. See the sections below for more information. + +#### Use a Custom ServiceAccount To use the SDK with custom RBAC permissions, provide the name for a custom ServiceAccount object during installation. When a service account is provided, the SDK uses the RBAC permissions granted to the service account and does not create the default Role, RoleBinding, or ServiceAccount objects. @@ -81,15 +341,15 @@ To install the SDK with custom RBAC: 1. Create custom Role, RoleBinding, and ServiceAccount objects. The Role must meet the minimum requirements described in [Minimum RBAC Requirements](#minimum-rbac-requirements) above. 1. During installation, provide the name of the service account that you created by including `--set replicated.serviceAccountName=CUSTOM_SERVICEACCOUNT_NAME`. - **Example**: + **Example**: - ``` - helm install wordpress oci://registry.replicated.com/my-app/beta/wordpress --set replicated.serviceAccountName=mycustomserviceaccount - ``` + ``` + helm install wordpress oci://registry.replicated.com/my-app/beta/wordpress --set replicated.serviceAccountName=mycustomserviceaccount + ``` - For more information about installing with Helm, see [Install with Helm](/vendor/install-with-helm). + For more information about installing with Helm, see [Install with Helm](/vendor/install-with-helm). -#### Custom ClusterRole +#### Use a Custom ClusterRole To use the SDK with an existing ClusterRole, provide the name for a custom ClusterRole object during installation. When a cluster role is provided, the SDK uses the RBAC permissions granted to the cluster role and does not create the default RoleBinding. Instead, the SDK creates a ClusterRoleBinding as well as a ServiceAccount object. @@ -98,13 +358,13 @@ To install the SDK with a custom ClusterRole: 1. Create a custom ClusterRole object. The ClusterRole must meet at least the minimum requirements described in [Minimum RBAC Requirements](#minimum-rbac-requirements) above. However, it can also provide additional permissions that can be used by the SDK, such as listing cluster Nodes. 1. During installation, provide the name of the cluster role that you created by including `--set replicated.clusterRole=CUSTOM_CLUSTERROLE_NAME`. - **Example**: + **Example**: - ``` - helm install wordpress oci://registry.replicated.com/my-app/beta/wordpress --set replicated.clusterRole=mycustomclusterrole - ``` + ``` + helm install wordpress oci://registry.replicated.com/my-app/beta/wordpress --set replicated.clusterRole=mycustomclusterrole + ``` - For more information about installing with Helm, see [Install with Helm](/vendor/install-with-helm). + For more information about installing with Helm, see [Install with Helm](/vendor/install-with-helm). ## Set Environment Variables {#env-var} @@ -270,219 +530,4 @@ This is the format produced by `kubectl create secret tls --cert=< replicated: tlsCertSecretName: YOUR_TLS_SECRET ``` - Where `YOUR_TLS_SECRET` is the secret in the namespace containing the TLS certificate and key. - -## Minimal RBAC - -With the Replicated SDK version 1.7.0 and later, you can enable the use of a less-permissive RBAC role for the SDK pod by setting the `replicated.minimalRBAC` Helm value in your Helm chart. - -```yaml -# Helm chart values.yaml - -replicated: - minimalRBAC: true -``` - -If statusInformers are not set manually, this RBAC role will include permissions to `get`, `list`, and `watch` all secrets, deployments, statefulsets, daemonsets, services, ingresses, PVCs, pods, replicasets, and endpoints within the namespace. -This allows Replicated to discover the Helm chart secret for your application, parse it to determine what resources to monitor, and then monitor those resources. - -```yaml -# Generated RBAC role with no statusInformers - -apiVersion: rbac.authorization.k8s.io/v1 -kind: Role -metadata: - name: replicated-role -rules: -- apiGroups: - - "" - resources: - - secrets - verbs: - - create -- apiGroups: - - "" - resourceNames: - - replicated - - replicated-instance-report - - replicated-custom-app-metrics-report - - replicated-meta-data - resources: - - secrets - verbs: - - update -- apiGroups: - - apps - resourceNames: - - replicated - resources: - - deployments - verbs: - - get -- apiGroups: - - apps - resources: - - replicasets - verbs: - - get -- apiGroups: - - "" - resources: - - pods - verbs: - - get -- apiGroups: - - "" - resourceNames: - - replicated - resources: - - secrets - verbs: - - get -- apiGroups: - - "" - resources: - - secrets - verbs: - - get - - list -- apiGroups: - - apps - resources: - - deployments - - replicasets - - statefulsets - - daemonsets - verbs: - - get - - list - - watch -- apiGroups: - - "" - resources: - - services - - endpoints - - persistentvolumeclaims - verbs: - - get - - list - - watch -- apiGroups: - - networking.k8s.io - resources: - - ingresses - verbs: - - get - - list - - watch -- apiGroups: - - "" - resources: - - pods - verbs: - - list -``` - -If statusInformers are set manually, then the generated role will not be created with the ability to access all secrets, and other resources will be specified by name when possible. -An example statusInformer configuration and generated role is presented below. - -```yaml -# Helm chart values.yaml - -replicated: - minimalRBAC: true - statusInformers: - - deployment/replicated - - deployment/myapp - - service/replicated - - service/myapp -``` - -```yaml -# Generated RBAC role with deployment/replicated, deployment/myapp, service/replicated and service/myapp statusinformers - -apiVersion: rbac.authorization.k8s.io/v1 -kind: Role -metadata: - name: replicated-role -rules: -- apiGroups: - - "" - resources: - - secrets - verbs: - - create -- apiGroups: - - "" - resourceNames: - - replicated - - replicated-instance-report - - replicated-custom-app-metrics-report - - replicated-meta-data - resources: - - secrets - verbs: - - update -- apiGroups: - - apps - resourceNames: - - replicated - resources: - - deployments - verbs: - - get -- apiGroups: - - apps - resources: - - replicasets - verbs: - - get -- apiGroups: - - "" - resources: - - pods - verbs: - - get -- apiGroups: - - "" - resourceNames: - - replicated - resources: - - secrets - verbs: - - get -- apiGroups: - - apps - resources: - - deployments - verbs: - - list - - watch -- apiGroups: - - apps - resourceNames: - - replicated - - myapp - resources: - - deployments - verbs: - - get -- apiGroups: - - "" - resources: - - services - - endpoints - verbs: - - list - - watch -- apiGroups: - - "" - resourceNames: - - replicated - - myapp - resources: - - services - - endpoints - verbs: - - get -``` + Where `YOUR_TLS_SECRET` is the secret in the namespace containing the TLS certificate and key. \ No newline at end of file From 58d5578563516e0a3af461863817b9114db3631a Mon Sep 17 00:00:00 2001 From: Paige Calvert Date: Fri, 20 Jun 2025 13:17:43 -0600 Subject: [PATCH 6/9] edits --- docs/vendor/replicated-sdk-customizing.md | 43 ++++++++++++----------- 1 file changed, 22 insertions(+), 21 deletions(-) diff --git a/docs/vendor/replicated-sdk-customizing.md b/docs/vendor/replicated-sdk-customizing.md index 3aa6a9a045..8339725e07 100644 --- a/docs/vendor/replicated-sdk-customizing.md +++ b/docs/vendor/replicated-sdk-customizing.md @@ -8,7 +8,7 @@ For information about how to use a custom domain for the Replicated SDK image, s This section describes role-based access control (RBAC) for the Replicated SDK, including the default RBAC, minimum RBAC requirements, and how to install the SDK with custom RBAC. -It also describes how to enable the `replicated.minimalRBAC` field to use a less-permissive default RBAC role for the Replicated SDK 1.7.0 and later. +It also describes how to enable the `replicated.minimalRBAC` field to use a less-permissive default RBAC role for the Replicated SDK version 1.7.0 and later. ### Enable `minimalRBAC` @@ -154,7 +154,7 @@ rules: #### Default `minimalRBAC` Role With Custom Status Informers {#default-status-informers} -If you defined custom status informers for your application, then the default `minimalRBAC` role includes permissions only for the specific resources that you defined as status informers. These resources are specified by name when possible. +If you defined custom status informers for your application, then the default `minimalRBAC` role is _not_ created with the ability to access all secrets, and other resources are specified by name when possible. For example, the following custom `statusInformer` configuration defines specific Deployment and Service resources as status informers for the application: @@ -302,35 +302,36 @@ rules: - replicated-meta-data ``` -### Minimum RBAC Requirements +### Install the SDK with Custom RBAC + +This section describes how to install the SDK with custom RBAC permissions, include the minimum RBAC requirements for custom roles. To install with custom RBAC, you can use a custom ServiceAccount or a custom ClusterRole. See the sections below for more information. + +#### Minimum RBAC Requirements This section describes the minimum RBAC permissions required by the Replicated SDK. Any custom RBAC role that you create must include these permissions at minimum. -The SDK requires the following minimum RBAC permissions: +The SDK requires the following minimum RBAC permissions to start: * Create Secrets. * Get and update Secrets named `replicated`, `replicated-instance-report`, `replicated-meta-data`, and `replicated-custom-app-metrics-report`. * Get the `replicated` deployment. * Get the `replicaset` and `pods` corresponding to the `replicated` deployment. -* The SDK requires the following minimum RBAC permissions for status informers: - * If you defined custom status informers, then the SDK must have permissions to `list` and `watch` all the types of resources listed in the `replicated.statusInformers` array in your Helm chart `values.yaml` file, as well as the ability to `get` the named resource. - - For instance, if you have a single status informer `deployment/myapp`, then the SDK requires permissions to `list` and `watch` all deployments as well as `get` the `myapp` deployment. - * If you did _not_ define custom status informers, then the SDK must have permissions to `get`, `list`, and `watch` the following resources: + +The SDK requires the following minimum RBAC permissions for status informers: +* If you defined custom status informers, then the SDK must have permissions to `list` and `watch` all the types of resources listed in the `replicated.statusInformers` array in your Helm chart `values.yaml` file, as well as the ability to `get` the named resource. + + For example, if you have a single status informer `deployment/myapp`, then the SDK requires permissions to `list` and `watch` all deployments as well as `get` the `myapp` deployment. +* If you did _not_ define custom status informers, then the SDK must: + * Have permissions to `get`, and `list` all secrets within the namespace in order to discover the Helm Chart secret for your app. + * Have permissions to `get`, `list`, and `watch` the following resources: * Deployments - * Daemonsets + * DaemonSets * Ingresses * PersistentVolumeClaims - * Statefulsets - * Services - * For any Ingress resources used as status informers, the SDK requires `get` permissions for the Service resources listed in the `backend.Service.Name` field of the Ingress resource. - * For any Daemonset and Statefulset resources used as status informers, the SDK requires `list` permissions for pods in the namespace. - * For any Service resources used as status informers, the SDK requires `get` permissions for Endpoint resources with the same name as the service. - - The Replicated Vendor Portal uses status informers to provide application status data. For more information, see [Helm Installations](/vendor/insights-app-status#helm-installations) in _Enabling and Understanding Application Status_. - -### Install the SDK with Custom RBAC - -This section describes how to install the SDK with custom RBAC permissions. To install with custom RBAC, you can use a custom ServiceAccount or a custom ClusterRole. See the sections below for more information. + * StatefulSets + * Services +* For any Ingress resources used as status informers, the SDK requires `get` permissions for the Service resources listed in the `backend.Service.Name` field of the Ingress resource. +* For any DaemonSet and StatefulSet resources used as status informers, the SDK requires `list` permissions for pods in the namespace. +* For any Service resources used as status informers, the SDK requires `get` permissions for Endpoint resources with the same name as the service. #### Use a Custom ServiceAccount From 56abc918d13de7479342adc44ab130218e52680a Mon Sep 17 00:00:00 2001 From: Andrew Lavery Date: Fri, 20 Jun 2025 15:49:03 -0400 Subject: [PATCH 7/9] rearrange and consolidate --- docs/vendor/replicated-sdk-customizing.md | 96 +++++++++++------------ 1 file changed, 45 insertions(+), 51 deletions(-) diff --git a/docs/vendor/replicated-sdk-customizing.md b/docs/vendor/replicated-sdk-customizing.md index 8339725e07..0f20299b84 100644 --- a/docs/vendor/replicated-sdk-customizing.md +++ b/docs/vendor/replicated-sdk-customizing.md @@ -10,22 +10,48 @@ This section describes role-based access control (RBAC) for the Replicated SDK, It also describes how to enable the `replicated.minimalRBAC` field to use a less-permissive default RBAC role for the Replicated SDK version 1.7.0 and later. -### Enable `minimalRBAC` +### Default RBAC -With the Replicated SDK version 1.7.0 and later, you can enable the use of a less-permissive RBAC role for the SDK pod by setting the `replicated.minimalRBAC` Helm value in your Helm chart, as shown below: +This section describes the default RBAC role that is created for the Replicated SDK when the `replicated.minimalRBAC` field is false. -```yaml -# Helm chart values.yaml +The SDK creates default Role, RoleBinding, and ServiceAccount objects during installation. The default Role allows the SDK to get, list, and watch all resources in the namespace, to create Secrets, and to update the `replicated`, `replicated-instance-report`, `replicated-custom-app-metrics-report`, and `replicated-meta-data` Secrets: -replicated: - minimalRBAC: true +```yaml +apiVersion: rbac.authorization.k8s.io/v1 +kind: Role +metadata: + name: replicated-role +rules: +- apiGroups: + - '*' + resources: + - '*' + verbs: + - 'get' + - 'list' + - 'watch' +- apiGroups: + - '' + resources: + - 'secrets' + verbs: + - 'create' +- apiGroups: + - '' + resources: + - 'secrets' + verbs: + - 'update' + resourceNames: + - replicated + - replicated-instance-report + - replicated-custom-app-metrics-report + - replicated-meta-data ``` -For more information about the default RBAC role that is created when `minimalRBAC` is enabled, see [Default RBAC (`minimalRBAC: true`)](#default-rbac-true). +### Minimal RBAC -### Default RBAC (`minimalRBAC: true`) {#default-rbac-true} - -This section describes the default RBAC role that is created for the Replicated SDK when the `replicated.minimalRBAC` field is true. For the default RBAC when `minimalRBAC` is false, see [Default RBAC (`minimalRBAC: false`)](#default-rbac-false). +This section describes the default RBAC role that is created for the Replicated SDK when the `replicated.minimalRBAC` field is true in version 1.7.0 and later. The permissions included in the default `minimalRBAC` Role vary depending on if you defined custom _status informers_ for your application. See one of the following sections for more information: * [Default `minimalRBAC` Role Without Custom Status Informers](#default-no-status-informers) @@ -53,6 +79,15 @@ If you did _not_ define custom status informers for your application, then the d These permissions allow the SDK to discover the Helm chart secret for your application, parse it to determine what resources to monitor, and then monitor those resources. +To enable `minimalRBAC`, set the value in your Helm chart as shown below: + +```yaml +# Helm chart values.yaml + +replicated: + minimalRBAC: true +``` + The following shows the default RBAC role for the SDK when `minimalRBAC` is enabled and no customer status informers are defined: ```yaml @@ -261,47 +296,6 @@ rules: - get ``` -### Default RBAC (`minimalRBAC: false`) {#default-rbac-false} - -This section describes the default RBAC role that is created for the Replicated SDK when the `replicated.minimalRBAC` field is false. - -The SDK creates default Role, RoleBinding, and ServiceAccount objects during installation. The default Role allows the SDK to get, list, and watch all resources in the namespace, to create Secrets, and to update the `replicated`, `replicated-instance-report`, `replicated-custom-app-metrics-report`, and `replicated-meta-data` Secrets: - -```yaml -apiVersion: rbac.authorization.k8s.io/v1 -kind: Role -metadata: - labels: - {{- include "replicated.labels" . | nindent 4 }} - name: replicated-role -rules: -- apiGroups: - - '*' - resources: - - '*' - verbs: - - 'get' - - 'list' - - 'watch' -- apiGroups: - - '' - resources: - - 'secrets' - verbs: - - 'create' -- apiGroups: - - '' - resources: - - 'secrets' - verbs: - - 'update' - resourceNames: - - replicated - - replicated-instance-report - - replicated-custom-app-metrics-report - - replicated-meta-data -``` - ### Install the SDK with Custom RBAC This section describes how to install the SDK with custom RBAC permissions, include the minimum RBAC requirements for custom roles. To install with custom RBAC, you can use a custom ServiceAccount or a custom ClusterRole. See the sections below for more information. From 5ec9c05ff4318641986869017f7c6b5b57f4c563 Mon Sep 17 00:00:00 2001 From: Andrew Lavery Date: Fri, 20 Jun 2025 16:06:38 -0400 Subject: [PATCH 8/9] rewording more --- docs/vendor/replicated-sdk-customizing.md | 32 ++++++++++------------- 1 file changed, 14 insertions(+), 18 deletions(-) diff --git a/docs/vendor/replicated-sdk-customizing.md b/docs/vendor/replicated-sdk-customizing.md index 0f20299b84..76b62b75b9 100644 --- a/docs/vendor/replicated-sdk-customizing.md +++ b/docs/vendor/replicated-sdk-customizing.md @@ -8,13 +8,9 @@ For information about how to use a custom domain for the Replicated SDK image, s This section describes role-based access control (RBAC) for the Replicated SDK, including the default RBAC, minimum RBAC requirements, and how to install the SDK with custom RBAC. -It also describes how to enable the `replicated.minimalRBAC` field to use a less-permissive default RBAC role for the Replicated SDK version 1.7.0 and later. - ### Default RBAC -This section describes the default RBAC role that is created for the Replicated SDK when the `replicated.minimalRBAC` field is false. - -The SDK creates default Role, RoleBinding, and ServiceAccount objects during installation. The default Role allows the SDK to get, list, and watch all resources in the namespace, to create Secrets, and to update the `replicated`, `replicated-instance-report`, `replicated-custom-app-metrics-report`, and `replicated-meta-data` Secrets: +The SDK creates default Role, RoleBinding, and ServiceAccount objects during installation. When `replicated.minimalRBAC` is false, the default Role allows the SDK to get, list, and watch all resources in the namespace, to create Secrets, and to update the `replicated`, `replicated-instance-report`, `replicated-custom-app-metrics-report`, and `replicated-meta-data` Secrets: ```yaml apiVersion: rbac.authorization.k8s.io/v1 @@ -51,11 +47,11 @@ rules: ### Minimal RBAC -This section describes the default RBAC role that is created for the Replicated SDK when the `replicated.minimalRBAC` field is true in version 1.7.0 and later. +With the Replicated SDK version 1.7.0 and later, you can enable a fully-featured but less permissive RBAC role by setting `minimalRBAC` to true. -The permissions included in the default `minimalRBAC` Role vary depending on if you defined custom _status informers_ for your application. See one of the following sections for more information: -* [Default `minimalRBAC` Role Without Custom Status Informers](#default-no-status-informers) -* [Default `minimalRBAC` Role With Custom Status Informers](#default-status-informers) +The permissions included in the Minimal RBAC role vary depending on if you defined custom _status informers_ for your application. See one of the following sections for more information: +* [Default Minimal RBAC Role Without Custom Status Informers](#default-no-status-informers) +* [Default Minimal RBAC Role With Custom Status Informers](#default-status-informers)
What are status informers? @@ -63,9 +59,9 @@ The permissions included in the default `minimalRBAC` Role vary depending on if The Replicated Vendor Portal uses status informers to provide application status data. For more information about status informers, see [Helm Installations](/vendor/insights-app-status#helm-installations) in _Enabling and Understanding Application Status_.
-#### Default `minimalRBAC` Role Without Custom Status Informers {#default-no-status-informers} +#### Default Minimal RBAC Role Without Custom Status Informers {#default-no-status-informers} -If you did _not_ define custom status informers for your application, then the default `minimalRBAC` Role includes permissions for the SDK to `get`, `list`, and `watch` the following resources in the namespace: +If you did _not_ define custom status informers for your application, then the default minimal RBAC Role includes permissions for the SDK to `get`, `list`, and `watch` the following resources in the namespace: * Secrets * Deployments * StatefulSets @@ -79,7 +75,7 @@ If you did _not_ define custom status informers for your application, then the d These permissions allow the SDK to discover the Helm chart secret for your application, parse it to determine what resources to monitor, and then monitor those resources. -To enable `minimalRBAC`, set the value in your Helm chart as shown below: +To enable Minimal RBAC, set the value in your Helm chart as shown below: ```yaml # Helm chart values.yaml @@ -88,7 +84,7 @@ replicated: minimalRBAC: true ``` -The following shows the default RBAC role for the SDK when `minimalRBAC` is enabled and no customer status informers are defined: +The following shows the default RBAC role for the SDK when Minimal RBAC is enabled and no customer status informers are defined: ```yaml # Generated RBAC role with no statusInformers @@ -187,9 +183,9 @@ rules: - list ``` -#### Default `minimalRBAC` Role With Custom Status Informers {#default-status-informers} +#### Default Minimal RBAC Role With Custom Status Informers {#default-status-informers} -If you defined custom status informers for your application, then the default `minimalRBAC` role is _not_ created with the ability to access all secrets, and other resources are specified by name when possible. +If you defined custom status informers for your application, then the default Minimal RBAC role is _not_ created with the ability to access all secrets, and other resources are specified by name when possible. For example, the following custom `statusInformer` configuration defines specific Deployment and Service resources as status informers for the application: @@ -205,7 +201,7 @@ replicated: - service/myapp ``` -Given the custom `statusInformer` configuration above, the following `minimalRBAC` role is created: +Given the custom `statusInformer` configuration above, the following Minimal RBAC role is created: ```yaml # Generated RBAC role with deployment/replicated, deployment/myapp, service/replicated and service/myapp statusinformers @@ -298,11 +294,11 @@ rules: ### Install the SDK with Custom RBAC -This section describes how to install the SDK with custom RBAC permissions, include the minimum RBAC requirements for custom roles. To install with custom RBAC, you can use a custom ServiceAccount or a custom ClusterRole. See the sections below for more information. +To install with custom RBAC, you can use a custom ServiceAccount or a custom ClusterRole. See the sections below for more information. #### Minimum RBAC Requirements -This section describes the minimum RBAC permissions required by the Replicated SDK. Any custom RBAC role that you create must include these permissions at minimum. +Any custom RBAC role that you create must include these permissions. The SDK requires the following minimum RBAC permissions to start: * Create Secrets. From d24a1fcd584df1c3c1c6abdda14c7f6d482464e2 Mon Sep 17 00:00:00 2001 From: Paige Calvert Date: Fri, 20 Jun 2025 14:17:06 -0600 Subject: [PATCH 9/9] Update replicated-sdk-customizing.md --- docs/vendor/replicated-sdk-customizing.md | 22 ++++++++++------------ 1 file changed, 10 insertions(+), 12 deletions(-) diff --git a/docs/vendor/replicated-sdk-customizing.md b/docs/vendor/replicated-sdk-customizing.md index 76b62b75b9..3225d8de8a 100644 --- a/docs/vendor/replicated-sdk-customizing.md +++ b/docs/vendor/replicated-sdk-customizing.md @@ -6,7 +6,7 @@ For information about how to use a custom domain for the Replicated SDK image, s ## Customize RBAC for the SDK -This section describes role-based access control (RBAC) for the Replicated SDK, including the default RBAC, minimum RBAC requirements, and how to install the SDK with custom RBAC. +This section describes role-based access control (RBAC) for the Replicated SDK, including the default RBAC, minimal RBAC, and how to install the SDK with custom RBAC. ### Default RBAC @@ -47,7 +47,14 @@ rules: ### Minimal RBAC -With the Replicated SDK version 1.7.0 and later, you can enable a fully-featured but less permissive RBAC role by setting `minimalRBAC` to true. +With the Replicated SDK version 1.7.0 and later, you can enable a fully-featured but less permissive RBAC role by setting `minimalRBAC` to true in your Helm chart values, as shown below: + +```yaml +# Helm chart values.yaml + +replicated: + minimalRBAC: true +``` The permissions included in the Minimal RBAC role vary depending on if you defined custom _status informers_ for your application. See one of the following sections for more information: * [Default Minimal RBAC Role Without Custom Status Informers](#default-no-status-informers) @@ -75,15 +82,6 @@ If you did _not_ define custom status informers for your application, then the d These permissions allow the SDK to discover the Helm chart secret for your application, parse it to determine what resources to monitor, and then monitor those resources. -To enable Minimal RBAC, set the value in your Helm chart as shown below: - -```yaml -# Helm chart values.yaml - -replicated: - minimalRBAC: true -``` - The following shows the default RBAC role for the SDK when Minimal RBAC is enabled and no customer status informers are defined: ```yaml @@ -521,4 +519,4 @@ This is the format produced by `kubectl create secret tls --cert=< replicated: tlsCertSecretName: YOUR_TLS_SECRET ``` - Where `YOUR_TLS_SECRET` is the secret in the namespace containing the TLS certificate and key. \ No newline at end of file + Where `YOUR_TLS_SECRET` is the secret in the namespace containing the TLS certificate and key.