Skip to main content
Redhat Developers  Logo
  • Products

    Platforms

    • Red Hat Enterprise Linux
      Red Hat Enterprise Linux Icon
    • Red Hat AI
      Red Hat AI
    • Red Hat OpenShift
      Openshift icon
    • Red Hat Ansible Automation Platform
      Ansible icon
    • View All Red Hat Products

    Featured

    • Red Hat build of OpenJDK
    • Red Hat Developer Hub
    • Red Hat JBoss Enterprise Application Platform
    • Red Hat OpenShift Dev Spaces
    • Red Hat OpenShift Local
    • Red Hat Developer Sandbox

      Try Red Hat products and technologies without setup or configuration fees for 30 days with this shared Openshift and Kubernetes cluster.
    • Try at no cost
  • Technologies

    Featured

    • AI/ML
      AI/ML Icon
    • Linux
      Linux Icon
    • Kubernetes
      Cloud icon
    • Automation
      Automation Icon showing arrows moving in a circle around a gear
    • View All Technologies
    • Programming Languages & Frameworks

      • Java
      • Python
      • JavaScript
    • System Design & Architecture

      • Red Hat architecture and design patterns
      • Microservices
      • Event-Driven Architecture
      • Databases
    • Developer Productivity

      • Developer productivity
      • Developer Tools
      • GitOps
    • Automated Data Processing

      • AI/ML
      • Data Science
      • Apache Kafka on Kubernetes
    • Platform Engineering

      • DevOps
      • DevSecOps
      • Ansible automation for applications and services
    • Secure Development & Architectures

      • Security
      • Secure coding
  • Learn

    Featured

    • Kubernetes & Cloud Native
      Openshift icon
    • Linux
      Rhel icon
    • Automation
      Ansible cloud icon
    • AI/ML
      AI/ML Icon
    • View All Learning Resources

    E-Books

    • GitOps Cookbook
    • Podman in Action
    • Kubernetes Operators
    • The Path to GitOps
    • View All E-books

    Cheat Sheets

    • Linux Commands
    • Bash Commands
    • Git
    • systemd Commands
    • View All Cheat Sheets

    Documentation

    • Product Documentation
    • API Catalog
    • Legacy Documentation
  • Developer Sandbox

    Developer Sandbox

    • Access Red Hat’s products and technologies without setup or configuration, and start developing quicker than ever before with our new, no-cost sandbox environments.
    • Explore Developer Sandbox

    Featured Developer Sandbox activities

    • Get started with your Developer Sandbox
    • OpenShift virtualization and application modernization using the Developer Sandbox
    • Explore all Developer Sandbox activities

    Ready to start developing apps?

    • Try at no cost
  • Blog
  • Events
  • Videos

5 global environment variables provided by OpenShift GitOps

March 6, 2023
Gerald Nunn
Related topics:
GitOpsOperatorsSecurity
Related products:
Red Hat OpenShiftRed Hat OpenShift Container Platform

Share:

    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.

    Environment Variable Default Description
    ARGOCD_CLUSTER_CONFIG_NAMESPACES None OpenShift GitOps instances in the identified namespaces are granted limited additional permissions to manage specific cluster-scoped resources, which include platform operators, optional OLM operators, user management, etc.

    Multiple namespaces can be specified via a comma delimited list.

    CONTROLLER_CLUSTER_ROLE None This environment variable enables administrators to configure a common cluster role to use across all managed namespaces in the role bindings the operator creates for the Argo CD application controller.
    DISABLE_DEFAULT_ARGOCD_CONSOLELINK false When set to `true`, this will disable the ConsoleLink for Argo CD, which appears in the OpenShift Console Application Launcher.
    DISABLE_DEFAULT_ARGOCD_INSTANCE false When set to `true`, this will disable the default 'ready-to-use' installation of Argo CD in the `openshift-gitops` namespace.
    SERVER_CLUSTER_ROLE None This environment variable enables Administrators to configure a common cluster role to use across all of the managed namespaces in the role bindings the operator creates for the Argo CD server.

     

    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:

    Resource (API Group)

    What it Manages

    operators.coreos.com, operator.openshift.io

    Optional operators managed by OLM

    user.openshift.io , rbac.authorization.k8s.io

    Groups, users, and their permissions.

    config.openshift.io

    Control plane Operators managed by CVO are used to configure cluster-wide build configuration, registry configuration, scheduler policies, etc.

    storage.k8s.io

    Storage.

    console.openshift.io

    Console customization.

    machine.openshift.io, machineconfiguration.openshift.io

    Machine API (machines, MachineSets, machine configuration, etc.)

    compliance.openshift.io

    Compliance operator, ScanSettingBinding only

    Other

    Namespaces, PV, PVC, and ConfigMaps

     

    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.

    A screenshot of the console link in the OpenSift applications menu.
    Figure 1. The console link in the OpenSift applications menu.

    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

    Related Posts

    • How OpenShift GitOps notifications can trigger pipelines

    • Install Red Hat OpenShift Operators on your laptop using Red Hat CodeReady Containers and Red Hat Marketplace

    • Prevent auto-reboot during Argo CD sync with machine configs

    • Making environment variables accessible in front-end containers

    Recent Posts

    • What qualifies for Red Hat Developer Subscription for Teams?

    • How to run OpenAI's gpt-oss models locally with RamaLama

    • Using DNS over TLS in OpenShift to secure communications

    • Scaling DeepSeek and Sparse MoE models in vLLM with llm-d

    • Multicluster authentication with Ansible Automation Platform

    What’s up next?

    Learn how to deploy an application on a cluster using Red Hat OpenShift Service on AWS. This learning path uses a pre-built application to allow you to become more familiar with OpenShift and Kubernetes features.

    Start learning
    Red Hat Developers logo LinkedIn YouTube Twitter Facebook

    Products

    • Red Hat Enterprise Linux
    • Red Hat OpenShift
    • Red Hat Ansible Automation Platform

    Build

    • Developer Sandbox
    • Developer Tools
    • Interactive Tutorials
    • API Catalog

    Quicklinks

    • Learning Resources
    • E-books
    • Cheat Sheets
    • Blog
    • Events
    • Newsletter

    Communicate

    • About us
    • Contact sales
    • Find a partner
    • Report a website issue
    • Site Status Dashboard
    • Report a security problem

    RED HAT DEVELOPER

    Build here. Go anywhere.

    We serve the builders. The problem solvers who create careers with code.

    Join us if you’re a developer, software engineer, web designer, front-end designer, UX designer, computer scientist, architect, tester, product manager, project manager or team lead.

    Sign me up

    Red Hat legal and privacy links

    • About Red Hat
    • Jobs
    • Events
    • Locations
    • Contact Red Hat
    • Red Hat Blog
    • Inclusion at Red Hat
    • Cool Stuff Store
    • Red Hat Summit
    © 2025 Red Hat

    Red Hat legal and privacy links

    • Privacy statement
    • Terms of use
    • All policies and guidelines
    • Digital accessibility

    Report a website issue