5 global environment variables provided by OpenShift GitOps

Red Hat OpenShift GitOps provides a compelling out-of-the-box experience for the majority of Red Hat OpenShift customers. However, there are times when organizations have specific requirements to satisfy that require additional tuning. OpenShift GitOps provides a number of global-level environment variables that organizations can apply to tailor their experience.

5 Environment variables: Overview

OpenShift GitOps supports the use of environment variables to control operator behavior in specific areas. The following table provides a brief overview of five variables from the upstream documentation. Note that this list can change between releases, so it's always a good idea to verify new, deprecated, or removed variables.

 

The environment variables can be attached to the subscription object, automatically including them in the operator deployment managed by the subscription. Specifying environment variables in the subscription object is done by including them in spec.config.env as follows:

apiVersion: operators.coreos.com/v1alpha1
kind: Subscription
metadata:
  name: openshift-gitops-operator
  namespace: openshift-operators
spec:
  channel: gitops-1.7
  config:
    env:
    - name: ARGOCD_CLUSTER_CONFIG_NAMESPACES
      value: openshift-gitops, gitops
    - name: CONTROLLER_CLUSTER_ROLE
      value: gitops-controller
  installPlanApproval: Automatic
  name: openshift-gitops-operator
  source: redhat-operators
  sourceNamespace: openshift-marketplace

5 Environment variables: Details

The subsequent sections provide more details about the five environment variables.

1. ARGOCD_CLUSTER_CONFIG_NAMESPACES

In OpenShift GitOps, the operator can deploy Argo CD in one of two scopes: cluster or namespace. A cluster-scoped instance is intended to deploy and manage resources across a cluster, whereas namespace scope is limited to a set of specified namespaces. Most importantly, cluster scoped instances have access to cluster-level resources and thus are typically, but not always, used for cluster configuration.

In OpenShift GitOps, the default instance deployed in the openshift-gitops namespace is cluster scoped and, as mentioned previously, intended for cluster configuration. Any other instances deployed are namespace scoped by default and only have access to resources in the namespace to which they are deployed.

To prevent users from deploying Argo CD instances with cluster-level privileges, a cluster administrator must identify the namespaces with cluster privileges by using this environment variable in the subscription object. Since namespace administrators do not have access to the subscription object, this prevents them from elevating the privileges of their own instance and bypassing cluster security.

When an instance is designated as cluster scoped, the operator will automatically create a set of ClusterRole and ClusterRoleBindings for the application controller and server service accounts in that namespace. This default role is not intended to be the equivalent of the standard cluster-admin role. It is given a much smaller set of permissions as follows:

 

These permissions can be extended by creating additional ClusterRole/ClusterRoleBinding as needed.

2. CONTROLLER_CLUSTER_ROLE

When OpenShift GitOps is deployed in namespace mode, it will create a set of roles and RoleBindings in every namespace that the instance manages to enable the application controller to deploy resources into those namespaces. The cluster administrator indicates these managed namespaces by labeling the namespace:

argocd.argoproj.io/managed-by: <namespace-of-target-gitops>

The roles that the operator in the namespace creates are namespace scoped and only have access to namespace resources. It cannot perform any actions outside of the namespaces it manages.

While the out-of-the-box role works well for many use cases, organizations may need to modify this role depending on their security requirements, additional resources they want to manage, etc. For example, an organization with security needs driven by regulatory requirements may wish to define a specific set of reduced permissions to meet those requirements.

This environment variable enables the cluster administrator to specify an alternate cluster role instead of the default operator-created role for the application controller. When this variable is provided, the operator will not create a default Role in the namespace but rather only create a RoleBinding in the namespace to the provided cluster role. It is up to the administrator to create this cluster role, having full control over the permissions.

One key aspect to note when defining your own role is that Argo CD will attempt to interact with all resources. When using this feature, you must either provide permission to view/get/watch all resources in your custom cluster role or configure the ArgoCD Custom Resource to include or exclude specific resources via resourceInclusions or resourceExclusions defined in the role.

As an example, in my own installations, I like to specify an alternate ClusterRole that has the following features:

• The Kubernetes ClusterRole aggregation feature allows the cluster role to be easily extended without directly modifying the role.
• The view all permissions role is aggregated into the above ClusterRole.
• The write permissions role incorporates the out-of-the-box admin ClusterRole that OpenShift uses for namespace administrators. The admin is a cluster aggregated role that components like OLM leverage so that when new operators are installed, their resources are automatically aggregated into the role.

Given all this, the following is an example of the role I used where the variable CONTROLLER_CLUSTER_ROLE is set to the gitops-controller ClusterRole.

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  annotations:
    rbac.authorization.kubernetes.io/autoupdate: "true"
  name: gitops-controller
aggregationRule:
  clusterRoleSelectors:
  - matchLabels:
      gitops/aggregate-to-controller: "true"
rules: []
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: gitops-controller-admin
  labels:
    gitops/aggregate-to-controller: "true"
aggregationRule:
  clusterRoleSelectors:
  - matchLabels:
      rbac.authorization.k8s.io/aggregate-to-admin: "true"
rules: []
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: gitops-controller-view
  labels:
    gitops/aggregate-to-controller: "true"
rules:
- apiGroups:
  - '*'
  resources:
  - '*'
  verbs:
  - get
  - list
  - watch

3. DISABLE_DEFAULT_ARGOCD_CONSOLELINK

By default, the operator will create a default instance in the openshift-gitops namespace and create a Console Link to access this instance. This custom link is rendered in the OpenShift console under the Applications menu, visible to all OpenShift users, as shown in Figure 1.

However, this instance is typically used for cluster configuration, and we do not want tenants on the cluster to access this instance. While RBAC controls access to the instance, showing a link to users who cannot access it can be confusing.

Setting this variable to true will remove the ConsoleLink, and it will no longer appear in the console.

4. DISABLE_DEFAULT_ARGOCD_INSTANCE

As mentioned, the operator will create a cluster-scoped instance in the openshift-gitops namespace by default. Setting this environment variable to true will disable this behavior, and the default instance will not be created.

This can be useful when users do not require this instance (cluster configuration is managed remotely) or simply require a different namespace. An example of the latter could be users migrating from community Argo CD where the typical practice is to deploy in an argocd namespace.

5. SERVER_CLUSTER_ROLE

This environment variable is the equivalent of the previously discussed CONTROLLER_CLUSTER_ROLE except for the server component of Argo CD. It operates identically to that variable but binds the server service component to the specified ClusterRole.

In practice, there is typically much less need to customize or change this role than for the controller, but the option to do so is there.

Customizing with environment variables

This article described how to easily customize the behavior of the OpenShift GitOps operator using five environment variables in the Subscription object. If you have questions, feel free to comment below. We welcome your feedback.

Last updated: October 26, 2023