SupportConsoleDevelopersStart a trialContact

Understanding OpenShift GitOps

Red Hat OpenShift GitOps 1.15

Introduction to OpenShift GitOps

Red Hat OpenShift Documentation Team

Abstract

This document provides an overview of OpenShift GitOps and its features. It also provides a glossary that defines common OpenShift GitOps terms.

Chapter 1. What is GitOps?

GitOps is a declarative way to implement continuous deployment for cloud native applications. You can use GitOps to create repeatable processes for managing OpenShift Container Platform clusters and applications across multi-cluster Kubernetes environments. GitOps handles and automates complex deployments at a fast pace, saving time during deployment and release cycles.

The GitOps workflow pushes an application through development, testing, staging, and production. GitOps either deploys a new application or updates an existing one, so you only need to update the repository; GitOps automates everything else.

GitOps is a set of practices that use Git pull requests to manage infrastructure and application configurations. In GitOps, the Git repository is the only source of truth for system and application configuration. This Git repository contains a declarative description of the infrastructure you need in your specified environment and contains an automated process to make your environment match the described state. Also, it contains the entire state of the system so that the trail of changes to the system state are visible and auditable. By using GitOps, you resolve the issues of infrastructure and application configuration sprawl.

GitOps defines infrastructure and application definitions as code. Then, it uses this code to manage multiple workspaces and clusters to simplify the creation of infrastructure and application configurations. By following the principles of the code, you can store the configuration of clusters and applications in Git repositories, and then follow the Git workflow to apply these repositories to your chosen clusters. You can apply the core principles of developing and maintaining software in a Git repository to the creation and management of your cluster and application configuration files.

Chapter 2. About Red Hat OpenShift GitOps

Red Hat OpenShift GitOps is an Operator that uses Argo CD as the declarative GitOps engine. It enables GitOps workflows across multicluster OpenShift and Kubernetes infrastructure. Using Red Hat OpenShift GitOps, administrators can consistently configure and deploy Kubernetes-based infrastructure and applications across clusters and development lifecycles. Red Hat OpenShift GitOps is based on the open source project Argo CD and provides a similar set of features to what the upstream offers, with additional automation, integration into Red Hat OpenShift Container Platform and the benefits of Red Hat’s enterprise support, quality assurance and focus on enterprise security.

Note

Because Red Hat OpenShift GitOps releases on a different cadence from OpenShift Container Platform, the Red Hat OpenShift GitOps documentation is now available as separate documentation sets for each minor version of the product.

The Red Hat OpenShift GitOps documentation is available at https://docs.openshift.com/gitops/.

Documentation for specific versions is available using the version selector dropdown, or directly by adding the version to the URL, for example, https://docs.openshift.com/gitops/1.8.

In addition, the Red Hat OpenShift GitOps documentation is also available on the Red Hat Portal at https://access.redhat.com/documentation/en-us/red_hat_openshift_gitops/.

For additional information about the Red Hat OpenShift GitOps life cycle and supported platforms, refer to the Platform Life Cycle Policy.

Red Hat OpenShift GitOps ensures consistency in applications when you deploy them to different clusters in different environments, such as: development, staging, and production. Red Hat OpenShift GitOps organizes the deployment process around the configuration repositories and makes them the central element. It always has at least two repositories:

  1. Application repository with the source code
  2. Environment configuration repository that defines the desired state of the application

These repositories contain a declarative description of the infrastructure you need in your specified environment. They also contain an automated process to make your environment match the described state.

Red Hat OpenShift GitOps uses Argo CD to maintain cluster resources. Argo CD is an open-source declarative tool for the continuous deployment (CD) of applications. Red Hat OpenShift GitOps implements Argo CD as a controller so that it continuously monitors application definitions and configurations defined in a Git repository. Then, Argo CD compares the specified state of these configurations with their live state on the cluster.

Argo CD reports any configurations that deviate from their specified state. These reports allow administrators to automatically or manually resync configurations to the defined state. Therefore, Argo CD enables you to deliver global custom resources, like the resources that are used to configure OpenShift Container Platform clusters.

2.1. Key features

Red Hat OpenShift GitOps helps you automate the following tasks:

  • Ensure that the clusters have similar states for configuration, monitoring, and storage
  • Apply or revert configuration changes to multiple OpenShift Container Platform clusters
  • Associate templated configuration with different environments
  • Promote applications across clusters, from staging to production

2.2. Glossary of common terms for OpenShift GitOps

This glossary defines common OpenShift GitOps terms.

Application Controller (Argo CD Application Controller)

A controller that that performs the following actions:

  • Continuously watches the Git repository for changes
  • Monitors running applications
  • Compares the live state against the desired target state
  • Deploys new changes

Examples include Argo CD Application Controller detecting an OutOfSync application state and optionally taking corrective action.

Application custom resource (CR)
A YAML manifest that describes how you intend to deploy the resources of your Argo CD application.
Application custom resource definition (CRD)
A resource object representing a deployed Argo CD application instance in an environment.
ApplicationSet CRD (Argo CD application set)
A resource object and a CRD that automatically generates Argo CD applications based on the contents of an ApplicationSet CR. Cluster administrators use this CRD to define a single ApplicationSet CR to generate and update multiple corresponding Argo CD Application CRs.
ApplicationSet Controller (Argo CD ApplicationSet Controller)
A custom Kubernetes controller that exists within Argo CD and processes ApplicationSet CRs. This controller automatically creates, updates, and deletes Argo CD applications based on the contents of an ApplicationSet CR.
AppProject CRD
A CRD representing a logical grouping of applications within a project that governs where and how an application is allowed to manage resources. You can use the AppProject CRD to restrict where and how Argo CD users are allowed to access those applications. Managing the AppProject instances is an action typically restricted to Argo CD administrators.
Argo CD API server
A gRPC/REST server that exposes the API consumed by the web UI, CLI, continuous integration (CI), and continuous deployment (CD) systems.
Argo CD
An open-source declarative tool that automates the continuous deployment of Kubernetes-based infrastructure and applications across clusters and development lifecycles.
Argo CD application
An application that tracks the continuous deployment of individual Kubernetes resources from the GitOps repository, where the resources are defined as manifests, to a target Kubernetes cluster.
ArgoCD CRD
A Kubernetes CRD that describes the wanted state for a given Argo CD cluster that allows you to configure the components that make up an Argo CD cluster.
Argo CD instance
A single installation of Argo CD within a namespace that encapsulates all of the stateful aspects of a running Argo CD. Each Argo CD instance usually has a one-to-one mapping with an ArgoCD CR.
Argo CD project

An entity within Argo CD that refers to the Argo CD open source project’s specific concept of projects, and the corresponding AppProject CR.

An Argo CD project lets you define multiple namespaces and even clusters as allowed destinations. In contrast, an OpenShift project is restricted to a single namespace and is equivalent in concept to a namespace.

Argo CD project controls the behavior of Argo CD by restricting access to Git repositories and remote clusters. Examples include using the Argo CD project to control users by restricting who can access certain Argo CD applications or cluster resources through the Argo CD UI or Argo CD CLI.

Argo CD repository server (Argo CD-repo-server)

An Argo CD component that performs the following actions:

  • Reads from source repositories such as Git, Helm, or Open Container Initiative (OCI)
  • Generates corresponding application manifests
  • Runs custom configuration management tooling
  • Returns the result to the Argo CD Application Controller
Argo CD resource (ArgoCD CR)
A CR that describes the wanted state for a given Argo CD instance. It allows you to configure the components and settings that make up an Argo CD instance. At any given time, you can have only one ArgoCD CR within a namespace.
Argo CD server (Argo CD-server)
A server that provides the API and UI for Argo CD.
Argo Rollouts
A controller that you can use for managing the progressive deployment of applications hosted on Kubernetes and OpenShift Container Platform clusters. This controller has a set of CRDs that provides advanced deployment capabilities such as blue-green, canary, canary analysis, and experimentation.
Cluster-scoped instance
A mode in which Argo CD is configured to manage all resources on the cluster including certain cluster-specific resources such as cluster configuration, cluster RBAC, Operator resources, platform Operators, or secrets.
Control plane (GitOps control plane)

In the GitOps context, you can have a control plane for every Argo CD you install. A GitOps control plane is any namespace where you can install an Argo CD. This control plane allows you to provision, manage, and operate Argo CD across networks, instances, and clusters.

Within a control plane namespace, Argo CD maintains a set of following Kubernetes resources, which define the continuous deployment between the source Git repository and destination clusters:

  • Argo CD Application CRs
  • ConfigMap API objects
  • Secret objects representing the GitOps repository credentials and cluster credentials for deployment targets

openshift-gitops is the control plane namespace for the default Argo CD instance.

Declarative setup
A declarative description of the infrastructure required in your specified environment, for system and application setup or configuration. You can specify this description in a YAML configuration file in the Git repository. The declarative setup contains an automated process to make your environment and infrastucture match the described state. Examples include defining Argo CD applications, projects, and settings declaratively by using YAML manifests.
Default Argo CD instance (Default cluster-scoped instance)
A default instance that a Red Hat OpenShift GitOps Operator instantiates immediately after its installation, in the openshift-gitops namespace, with additional permissions for managing certain cluster-scoped resources.
GitOps
A declarative way to implement continuous deployment for cloud native applications. In GitOps, a Git repository contains deployment resources, which Argo CD keeps synchronizing with its cluster state.
GitOps CLI (GitOps argocd CLI)
A tool to configure and manage Red Hat OpenShift GitOps and Argo CD resources from the command line.
Instance scopes
Modes that determine how you want to operate an Argo CD instance. The available modes are cluster-scoped instance and namespace-scoped instance.
Live state
The live state of application resources on a target cluster.
Local cluster
A cluster where you install Argo CD.
Manifest
In the GitOps context, a manifest is a YAML representation of Kubernetes resources defined within a GitOps repository, with the intent to deploy those resources to a target Kubernetes cluster. Examples include the YAML representation of resources such as Deployment, ConfigMap, or Secret.
Multitenancy
A software architecture where a single software instance serves multiple distinct user groups.
Namespace-scoped instance (Application delivery instance)
A mode in which Argo CD is configured to manage resources in only certain namespaces on a cluster and use the resources for application delivery.
Notifications Controller (Argo CD Notifications Controller)
A controller that continuously monitors Argo CD applications and provides a flexible way to notify users about important changes in the application state.
Progressive delivery
In the GitOps context, progressive delivery is a process of releasing application updates in a controlled and gradual manner.
Red Hat OpenShift GitOps
An Operator that uses Argo CD as the declarative GitOps engine to enable GitOps workflows across multicluster OpenShift and Kubernetes infrastructures.
Refresh
The process of comparing the latest code in the Git repository with the live state and determining the difference. For example, in the Argo CD UI, when you click Refresh, Argo CD connects to an application’s target Git repository, retrieves the content, and then generates manifests from that content. Argo CD then compares that target state against the live cluster state.
Remote cluster
A cluster that you can add to Argo CD either declaratively or by using the GitOps CLI. Remote cluster is distinct from the local cluster where Argo CD is installed.
Resource Exclusion
A configuration you use to exclude resources from discovery and sync so that Argo CD is unaware of them.
Resource Inclusion
A configuration you use to include resources to discover, sync, and restrict the list of managed resources globally.
Single tenancy
A software architecture where a single software instance serves a single user or group of users.
Sync
The process of synchronizing the live state of an application’s cluster resources with the target state defined within the Git repository to ensure consistency. Examples include syncing an application by applying changes to a cluster by using the Argo CD UI.
Sync status
The status of an application that indicates whether the live state matches the target state.
Target state
The wanted state of application resources, as represented by files in a Git repository.
User-defined Argo CD instance

A custom Argo CD instance that you install and deploy to manage cluster configurations or deploy applications. By default, any new user-defined instance has permissions to manage resources only in the namespace where it is deployed.

You can create a user-defined Argo CD instance in any namespace, other than the openshift-gitops namespace.

Workload
Any process, usually defined within resources such as Deployment, StatefulSet, ReplicaSet, Job, or Pod, running within a container. Examples include a Spring Boot application, a NodeJS Express application, or a Ruby on Rails application.

2.3. Additional resources

Chapter 3. Gathering diagnostic information for support

When you open a support case, you must provide debugging information about your cluster to the Red Hat Support team. You can use the must-gather tool to collect diagnostic information for project-level resources, cluster-level resources, and Red Hat OpenShift GitOps components. 

Note

For prompt support, provide diagnostic information for both OpenShift Container Platform and Red Hat OpenShift GitOps.

3.1. About the must-gather tool

The oc adm must-gather CLI command collects the information from your cluster that is most likely needed for debugging issues, including:

  • Resource definitions
  • Service logs

By default, the oc adm must-gather command uses the default plugin image and writes into ./must-gather.local.

Alternatively, you can collect specific information by running the command with the appropriate arguments as described in the following sections:

  • To collect data related to one or more specific features, use the --image argument with an image, as listed in a following section.

    Example command

    $ oc adm must-gather --image=registry.redhat.io/openshift-gitops-1/must-gather-rhel8:v1.10.0

  • To collect the audit logs, use the -- /usr/bin/gather_audit_logs argument, as described in a following section.

    Example command

    $ oc adm must-gather -- /usr/bin/gather_audit_logs

    Note

    Audit logs are not collected as part of the default set of information to reduce the size of the files.

When you run oc adm must-gather, a new pod with a random name is created in a new project on the cluster. The data is collected on that pod and saved in a new directory that starts with must-gather.local. This directory is created in the current working directory.

Example pod

NAMESPACE                      NAME                 READY   STATUS      RESTARTS      AGE
...
openshift-must-gather-5drcj    must-gather-bklx4    2/2     Running     0             72s
openshift-must-gather-5drcj    must-gather-s8sdh    2/2     Running     0             72s
...

Optionally, you can run the oc adm must-gather command in a specific namespace by using the --run-namespace option.

Example command

$ oc adm must-gather --image=registry.redhat.io/openshift-gitops-1/must-gather-rhel8:v1.10.0

3.2. Collecting debugging data for Red Hat OpenShift GitOps

Use the oc adm must-gather CLI command to collect the following details about the cluster that is associated with Red Hat OpenShift GitOps:

  • The subscription and namespace of the Red Hat OpenShift GitOps Operator.
  • The namespaces where ArgoCD objects are available and the objects in those namespaces, such as ArgoCD, Applications, ApplicationSets, AppProjects, and configmaps.
  • A list of the namespaces that are managed by the Red Hat OpenShift GitOps Operator, and resources from those namespaces.
  • All GitOps-related custom resource objects and definitions.
  • Operator and Argo CD logs.
  • Warning and error-level events.

Prerequisites

  • You have logged in to the OpenShift Container Platform cluster as an administrator.
  • You have installed the OpenShift Container Platform CLI (oc).
  • You have installed the Red Hat OpenShift GitOps Operator.

Procedure

  1. Navigate to the directory where you want to store the debugging information.

  2. Run the oc adm must-gather command with the Red Hat OpenShift GitOps must-gather image: 

    $ oc adm must-gather --image=registry.redhat.io/openshift-gitops-1/must-gather-rhel8:<image_version_tag> 1
    1
    The must-gather image for GitOps.

    Example command

    $ oc adm must-gather --image=registry.redhat.io/openshift-gitops-1/must-gather-rhel8:v1.10.0

    The must-gather tool creates a new directory that starts with ./must-gather.local in the current directory. For example, ./must-gather.local.4157245944708210399.

  3. Create a compressed file from the directory that was just created. For example, on a computer that uses a Linux operating system, run the following command: 

    $ tar -cvaf must-gather.tar.gz must-gather.local.4157245944708210399 1
    1
    Replace must-gather-local.4157245944708210399 with the actual directory name.
  4. Attach the compressed file to your support case on the Red Hat Customer Portal.

3.3. Additional resources

Legal Notice

Copyright © 2024 Red Hat, Inc.
The text of and illustrations in this document are licensed by Red Hat under a Creative Commons Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). An explanation of CC-BY-SA is available at http://creativecommons.org/licenses/by-sa/3.0/. In accordance with CC-BY-SA, if you distribute this document or an adaptation of it, you must provide the URL for the original version.
Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.
Red Hat, Red Hat Enterprise Linux, the Shadowman logo, the Red Hat logo, JBoss, OpenShift, Fedora, the Infinity logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.
Linux® is the registered trademark of Linus Torvalds in the United States and other countries.
Java® is a registered trademark of Oracle and/or its affiliates.
XFS® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries.
MySQL® is a registered trademark of MySQL AB in the United States, the European Union and other countries.
Node.js® is an official trademark of Joyent. Red Hat is not formally related to or endorsed by the official Joyent Node.js open source or commercial project.
The OpenStack® Word Mark and OpenStack logo are either registered trademarks/service marks or trademarks/service marks of the OpenStack Foundation, in the United States and other countries and are used with the OpenStack Foundation's permission. We are not affiliated with, endorsed or sponsored by the OpenStack Foundation, or the OpenStack community.
All other trademarks are the property of their respective owners.
Red Hat logoGithubRedditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

© 2024 Red Hat, Inc.