From b07b6172ff789bade9fb11060e5bfc2e8478207c Mon Sep 17 00:00:00 2001 From: Clayton Cornell <131809008+clayton-cornell@users.noreply.github.com> Date: Thu, 12 Dec 2024 10:54:55 -0800 Subject: [PATCH] Add new OpenShift topic to Alloy docs (#2265) * Create new openshift topic * Add new info from review * Fix broken link * Updtae URL links --- docs/sources/set-up/install/openshift.md | 166 +++++++++++++++++++++++ 1 file changed, 166 insertions(+) create mode 100644 docs/sources/set-up/install/openshift.md diff --git a/docs/sources/set-up/install/openshift.md b/docs/sources/set-up/install/openshift.md new file mode 100644 index 000000000..3f4f16251 --- /dev/null +++ b/docs/sources/set-up/install/openshift.md @@ -0,0 +1,166 @@ +--- +canonical: https://grafana.com/docs/alloy/latest/set-up/install/openshift/ +description: Learn how to deploy Grafana Alloy on OpenShift +menuTitle: OpenShift +title: Deploy Grafana Alloy on OpenShift +weight: 530 +--- + +# Deploy {{% param "FULL_PRODUCT_NAME" %}} on OpenShift + +You can deploy {{< param "PRODUCT_NAME" >}} on the Red Hat OpenShift Container Platform (OCP). + +## Before you begin + +* These steps assume you have a working OCP environment. +* You can adapt the suggested policies and configuration to meet your specific needs and [security][] policies. + +## Configure RBAC + +You must configure Role-Based Access Control (RBAC) to allow secure access to Kubernetes and OCP resources. + +1. Download the [rbac.yaml][] configuration file. This configuration file defines the OCP verbs and permissions for {{< param "PRODUCT_NAME" >}}. +1. Review the `rbac.yaml` file and adapt as needed for your local environment. Refer to [Managing Role-based Access Control (RBAC)][rbac] topic in the OCP documentation for more information about updating and managing your RBAC configurations. + +## Run {{% param "PRODUCT_NAME" %}} as a non-root user + +You must configure {{< param "PRODUCT_NAME" >}} to [run as a non-root user][nonroot]. +This ensures that {{< param "PRODUCT_NAME" >}} complies with your OCP security policies. + +## Apply security context constraints + +OCP uses Security Context Constraints (SCC) to control Pod permissions. +Refer to [Managing security context constraints][scc] for more information about how you can define and enforce these permissions. +This ensures that the pods running {{< param "PRODUCT_NAME" >}} comply with OCP security policies. + +{{< admonition type="note" >}} +The security context is only configured at the container level, not at the container and deployment level. +{{< /admonition >}} + +You can apply the following SCCs when you deploy {{< param "PRODUCT_NAME" >}}. + +{{< admonition type="note" >}} +Not all of these SCCs are required for each use case. +You can adapt the SCCs to meet your local requirements and needs. +{{< /admonition >}} + +* `RunAsUser`: Specifies the user ID under which {{< param "PRODUCT_NAME" >}} runs. + You must configure this constraint to allow a non-root user ID. +* `SELinuxContext`: Configures the SELinux context for containers. + If you run {{< param "PRODUCT_NAME" >}} as root, you must configure this constraint to make sure that SELinux policies don't block {{< param "PRODUCT_NAME" >}}. + This SCC is generally not required to deploy {{< param "PRODUCT_NAME" >}} as a non-root user. +* `FSGroup`: Specifies the fsGroup IDs for file system access. + You must configure this constraint to give {{< param "PRODUCT_NAME" >}} group access to the files it needs. +* `Volumes`: Specifies the persistent volumes used for storage. + You must configure this constraint to give {{< param "PRODUCT_NAME" >}} access to the volumes it needs. + +## Example DaemonSet configuration + +The following example shows a DaemonSet configuration that deploys {{< param "PRODUCT_NAME" >}} as a non-root user: + +```yaml +apiVersion: aapps/v1 +kind: DaemonSet +metadata: + name: alloy-logs + namespace: monitoring +spec: + selector: + matchLabels: + app: alloy-logs + template: + metadata: + labels: + app: alloy-logs + spec: + containers: + - name: alloy-logs + image: grafana/alloy: + ports: + - containerPort: 12345 + # The security context configuration + securityContext: + readOnlyRootFilesystem: true + allowPrivilegeEscalation: false + runAsUser: 473 + runAsGroup: 473 + fsGroup: 1000 + volumes: + - name: log-volume + emptyDir: {} +``` + +Replace the following: + +* _``_: Set to the specific {{< param "PRODUCT_NAME" >}} version you are deploying. For example, `1.5.1`. + +{{< admonition type="note" >}} +This example uses the simplest volume type, `emptyDir`. In this example configuration, if your node restarts, your data will be lost. Make sure you set the volume type to a persistent storage location for production environments. Refer to [Using volumes to persist container data](https://docs.openshift.com/container-platform/latest/nodes/containers/nodes-containers-volumes.html) in the OpenShift documentation for more information. +{{< /admonition >}} + +## Example SSC definition + +The following example shows an SSC definition that deploys {{< param "PRODUCT_NAME" >}} as a non-root user: + +```yaml +kind: SecurityContextConstraints +apiVersion: security.openshift.io/v1 +metadata: + name: scc-alloy +runAsUser: + type: MustRunAs + uid: 473 +fsGroup: + type: MustRunAs + uid: 1000 +volumes: +- '*' +users: +- my-admin-user +groups: +- my-admin-group +seLinuxContext: + type: MustRunAs + user: + role: + type: + level: +``` + +Replace the following: + +* _``_: The user for your SELinux context. +* _``_: The role for your SELinux context. +* _``_: The container type for your SELinux context. +* _``_: The level for your SELinux context. + +Refer to [SELinux Contexts][selinux] in the RedHat documentation for more information on the SELinux context configuration. + +{{< admonition type="note" >}} +This example sets `volumes:` to `*`. In a production environment, you should set `volumes:` to only the volumes that are necessary for the deployment. For example: + +```yaml +volumes: + - configMap + - downwardAPI + - emptyDir + - persistentVolumeClaim + - secret +``` + +{{< /admonition >}} + +Refer to [Deploy {{< param "FULL_PRODUCT_NAME" >}}][deploy] for more information about deploying {{< param "PRODUCT_NAME" >}} in your environment. + +## Next steps + +* [Configure {{< param "PRODUCT_NAME" >}}][Configure] + +[rbac.yaml]: https://github.com/grafana/alloy/blob/main/operations/helm/charts/alloy/templates/rbac.yaml +[rbac]: https://docs.openshift.com/container-platform/latest/authentication/using-rbac.html +[security]: https://grafana.com/docs/grafana-cloud/monitor-infrastructure/kubernetes-monitoring/configuration/troubleshooting/#openshift-support +[nonroot]: ../../../configure/nonroot/ +[scc]: https://docs.openshift.com/container-platform/latest/authentication/managing-security-context-constraints.html +[Configure]: ../../../configure/linux/ +[deploy]: ../../deploy/ +[selinux]: https://docs.redhat.com/en/documentation/red_hat_enterprise_linux/6/html/security-enhanced_linux/chap-security-enhanced_linux-selinux_contexts#chap-Security-Enhanced_Linux-SELinux_Contexts