Managing GitOps Runtimes

Options to manage your GitOps Runtimes

Managing GitOps Runtimes

This article describes the options and actions to manage GitOps Runtimes after installation, including configuring the Runtime as an application, updating Git credentials, and more.
For options on monitoring GitOps Runtimes, see Monitoring GitOps Runtimes.

Configure Runtime as Argo CD application

Configure the GitOps Runtime as an Argo CD Application if you haven’t already done so during installation.

Configuring the GitOps Runtime as an Argo CD application ensures:

• Git as the single source of truth: The Runtime’s state is declaratively managed in Git, ensuring consistency, traceability, and version control over all its configurations.
• Automated reconciliation: Argo CD continuously monitors the Runtime’s desired state (as defined in Git), and automatically corrects any drift, ensuring alignment between the cluster and the Git repository.
• Visibility & monitoring: The Runtime is displayed in the GitOps Apps dashboard where you can view and check health and sync statuses.

How to

1. In the Codefresh UI, on the toolbar, click the Settings icon.
2. From the sidebar, select GitOps Runtimes.
3. Switch to the List View.
4. Select the GitOps Runtime to configure as an Argo CD application.
5. In the installation wizard, select Configure runtime as Argo CD Application.

The Runtime’s context menu now includes the Runtime Application option, which when selected takes you to the Current State tab in the GitOps Apps dashboard.

Upgrade GitOps Runtimes

Upgrade provisioned Hybrid GitOps Runtimes to install critical security updates, new functionality, and the latest versions of all components.

NOTE
For details on Argo CD versions and their compatible Kubernetes versions, see Argo CD versioning information and Kubernetes tested versions.

Changelog for new versions
Codefresh alerts you to newer versions of Runtimes, through Update Available! Notification in the List View’s Version column. A new version of the GtiOps Runtime includes a link to the changelog, detailing the changes in that version.
See also View changelogs for GitOps Runtimes.

Upgrade procedure
The upgrade procedure differs slightly depending on whether the GitOps Runtime has been configured as an Argo CD application or not:

• For Runtimes configured as Argo CD applications, you need to manually update the version in the Helm chart located in the Shared Configuration Repository.
• For other Runtimes, run the upgrade command.

How to

1. In the Codefresh UI, on the toolbar, click the Settings icon.
2. From the sidebar, select GitOps Runtimes.
3. To upgrade in List view, move to the Version column, and do the following:
   1. To see the changes in the new version of the Runtime, mouse over Update Available!, and click View Complete Change Log.
   2. Do one of the following:
      • To the right of the row with the Runtime to upgrade, click the context menu and select Upgrade.
      • Click the Runtime name, and then click Upgrade on the top-right.

4. To upgrade in Topology view: Click the Runtime cluster, and from the panel, click the context menu, and then select Upgrade Runtime.

5. Do one of the following depending on whether you have configured the Runtime as an Argo CD Application or not:
   • Runtimes configured as Argo CD applications: Continue from step 6.
   • Runtimes not configured as Argo CD applications: Continue from step 7.
6. For Runtimes configured as Argo CD applications, do the following:
   1. In your Shared Configuration Repository, go to resources/<runtime_name>/chart
      where:
      <runtime_name> is the name of the GitOps Runtime to upgrade.
   2. In chart.yaml, change the version number in both .version and .dependencies.version.
   3. Commit the change, and push to your Git server.

      apiVersion: v2
      appVersion: 1.0.0
      description: Codefresh gitops runtime umbrella chart
      name: codefresh-gitops-runtime
      version: <version>
      dependencies:
           - name: gitops-runtime
       repository: oci://quay.io/codefresh
       version: <version>
      

7. For Runtimes not configured as Argo CD applications, do the following:
   1. Copy and run the upgrade command:
      RELEASE_NAME=$(helm ls -n codefresh-gitops-runtime -q) && helm upgrade ${RELEASE_NAME} -n codefresh-gitops-runtime
   2. To exit the upgrade panel, click Close.

View changelogs for GitOps Runtimes

Each version of a GitOps Runtime includes a changelog detailing the changes in that release. Changelogs are available in ArtifactHub and GitHub

Changelog for latest Runtime release in Codefresh

In the GitOps Runtimes List view, the Version column displays the version currently installed.

Whenever there is a newer version of the Runtime, Helm chart, or both, the Update Available! notification appears in the same column.
Mouse over shows a link to the changelog for that version on GitHub.
The example below shows the changelog for the Latest release of the GitOps Runtime.

Changelogs for all Runtime releases

Changelogs for all versions, including historical versions, are available on ArtifactHub and GitHub.

• GitHub
• ArtifactHub
  On the right, select the chart version, and then click Changelog above.

Enable precise sync detection for monorepo apps

Enable the ACR Controller in GitOps Runtimes to precisely detect sync operations that triggered deployments for applications in monorepo setups.

When enabled, the ACR Controller:

• Identifies and tracks application-specific changes by analyzing the application’s source path.
• Compares revisions to identify the specific sync operation that triggered the promotion or deployment.
• Automatically adds the .app.status.operationState.operation.sync.changeRevision to application manifests.

To trigger and customize notifications for the identified revision, update the notification controller and configure the notification template accordingly.

How to

1. If needed, upgrade your Runtime to version 0.13.0 or higher.
2. In the Runtime's values.yaml, enable the ACR controller by adding the following to the argo-cd section:

   argo-cd:
     acrController:
       enabled: true
   

3. In the notification controller, switch the revision being used to .app.status.operationState.operation.sync.changeRevision.
   Here's an example with the new notification trigger:
   

       
       trigger.on-deployed: |
         - description: Application is synced and healthy. Triggered once per commit.
           when: app.status.health.status == 'Healthy' and app.status.operationState != nil and app.status.operationState.operation.sync.changeRevision != nil and app.status.operationState.phase in ['Succeeded']
           oncePer: app.status.operationState.operation.sync.changeRevision
           send:
             - app-deployed
     
     

4. Configure the notification template to report the changeRevision, as in the example below:

       
       message: "Author: {{(call .repo.GetCommitMetadata .app.status.operationState.operation.sync.changeRevision).Author}}, message: {{(call .repo.GetCommitMetadata .app.status.operationState.operation.sync.changeRevision).Message}}"
       
        

5. If you don't receive notifications, see Not receiving application-scoped sync notifications with ACR Controller.

Rollback GitOps Runtimes

After upgrading a GitOps Runtime, roll back to the previous or a specific version of the Runtime.
The rollback procedure differs slightly depending on whether the GitOps Runtime has been configured as an Argo CD application or not.

Rollback GitOps Runtimes configured as Argo CD applications

Manually change the version in the Helm chart (chart.yaml) located in the Shared Configuration Repository.

1. In your Shared Configuration Repository, go to:
   resources/<runtime_name>/chart
   where:
   <runtime_name> is the name of the GitOps Runtime to upgrade.
2. In chart.yaml, change the version number in both .version and .dependencies.version.
3. Commit the change, and push to your Git server.

Rollback other GitOps Runtimes

Rollback GitOps Runtimes not configured as Argo CD applications using Helm commands such as rollback or upgrade.

If you need details, see the documentation on Helm commands.

Update Git credentials for GitOps Runtimes

Provisioned GitOps Runtimes require valid Git Runtime tokens at all times to authenticate and authorize the Runtime. The Git Runtime token differs from the Git user token which is a personal access token unique to each user. As such, you can use the same Git Runtime token for multiple Runtimes.

When to update
If your Git Runtime token is valid, you can update it at any time by deleting the existing token and replacing it with a new token.

Otherwise, you have to update Git tokens in the following situations:

• Complete Installation status displayed in Sync column for Runtime
  You have installed the Runtime but need to update the Git credentials to complete the installation.
• Invalid, revoked, or expired tokens
  Codefresh automatically flags Runtimes with such tokens. It is mandatory to update the Git tokens to continue working with the platform.

Update methods
The methods for updating any Git token are the same regardless of the reason for the update:

• OAuth2 authorization, if your admin has registered an OAuth Application for Codefresh.
• Git access token authentication, by generating a Git Runtime token in your Git provider account with the correct scopes. You can update your Git Runtime token in the UI or through the CLI.

Update Git Runtime credentials in Codefresh UI

Before you begin

• To authenticate through a Git Runtime token, make sure your token is valid and has the required scopes

How to

1. In the Codefresh UI, on the toolbar, click the Settings icon.
2. From the sidebar, select GitOps Runtimes.
3. Switch to the List View.
4. Do one of the following:
   • To the right of the row with the Runtime to update, click the context menu and select Update Git Runtime Credentials.
   • Click the Runtime name, click the context-menu on the top-right, and then select Update Git Runtime Credentials.

5. Do one of the following:
   • If your admin has set up OAuth access, click Authorize Access to Git Provider. Go to step 6.
   • Alternatively, authenticate with an access token from your Git provider. Go to step 7.

6. For OAuth2 authorization:

   NOTE
   If the application is not registered, you get an error. Contact your admin for help.

   • Enter your credentials, and select Sign In.
   • If required, as for example if two-factor authentication is configured, complete the verification.

7. For Git token authentication, paste the generated token in the Git runtime token field.
8. Click Update Credentials.

Configure SSH for GitOps Runtimes

By default, Git repositories use the HTTPS protocol. You can also use SSH to connect Git repositories by entering the SSH private key.

NOTE
When SSH is configured for a GitOps Runtime, when creating/editing Git-Source applications, you can select HTTPS OR SSH as the protocol to connect to the Git repository. See Repository URL in Application Source definitions.

SSH keys For more information on generating SSH private keys, see the official documentation:

• GitHub

Before you begin Copy the SSH private key for your Git provider

How to

1. In the Codefresh UI, make sure you are in GitOps Runtimes.
2. From the List View, select the runtime for which to configure SSH.
3. From the context menu with the additional actions on the top-right, select Update Git Runtime Credentials.

4. Expand Connect Repo using SSH, and then paste the raw SSH private key into the field.

5. Click Update Credentials.

View/download logs for GitOps Runtimes

Logs are available for installed GitOps Runtimes, both for the Runtime and for individual Runtime components. Download log files for offline viewing and analysis, or view online logs for a Runtime component and download if needed for offline analysis. Online logs support free-text search, search-result navigation, and line-wrap for enhanced readability.

Log files include events from the date of the application launch, with the newest events listed first.

Download logs for GitOps Runtimes

Download the log file for a GitOps Runtime. The Runtime log is downloaded as a .tar.gz file, which contains the individual log files for each runtime component.

1. In the Codefresh UI, on the toolbar, click the Settings icon.
2. From the sidebar, select GitOps Runtimes.
3. If needed, switch to List View, and then select the runtime for which to download logs.
4. From the context menu, select Download All Logs. The log file is downloaded to the Downloads folder or the folder designated for downloads, with the filename, <runtime-name>.tar.gz. For example, codefreshv2-production2.tar.gz.

View/download logs for Runtime components

View online logs for any Runtime component, and if needed, download the log file for offline viewing and analysis.

NOTE
Downloading logs for Runtime components is supported from Runtime v0.1.39 and higher.

Online logs show up to 1000 of the most recent events (lines), updated in real time. Downloaded logs include all the events, from the date and time of application launch to the date and time of download.

1. In the Codefresh UI, on the toolbar, click the Settings icon.
2. From the sidebar, select GitOps Runtimes.
3. If needed, switch to List View, and then select the Runtime.
4. In the Runtime Components tab, from the context menu of the required component, select View Logs.

5. Do the following:
   • To search for any string, type the free-text to search for, and click the next and previous buttons to navigate between the search results.
   • To switch on line-wrap for readability, click Wrap.

6. To download the log, click Download. The file is downloaded as <component-name>.log.

Reset Shared Configuration Repository for GitOps Runtimes

When you install the first GitOps Runtime in your account, as part of the setup, Codefresh creates the Shared Configuration Repository in your Git provider account and validates the URL. The Shared Configuration Repo is used for all GitOps Runtimes you add to the same account.

As a Codefresh admin, you can reset the repo defined for your account if the URL is either incorrect or missing, or if there are no active GitOps Runtimes. See Reset Shared Configuration Repo.

Configure Deep Links to applications & resources

Deep Links is an Argo CD feature that redirects users to third-party applications/platforms by surfacing links to the same in Argo CD projects, applications, and resources. Read all about it in Argo CD Deep Links.

In Codefresh, you can configure deep links to third-party applications/platforms in the argocd-cm ConfigMap, located in the repo where you installed the GitOps Runtime. When configured, deep links are displayed in the application’s Current State tab in Tree view. See Working with resources in Tree View.

NOTE
Deep link configuration in Codefresh requires Runtime v0.1.27 or higher.

1. Go to the <hybrid-gitops-installation-repo>/bootstrap/argo-cd/kustomization.yaml.
2. Configure deep links as in the example below.

...
configMapGenerator:
- name: argocd-cm
  behavior: merge
  literals:
  - |
    resource.links:=- url: https://<mycompany>.splunk.com
        title: Splunk
        description: jf
        icon.class: "fa-book"
  - |
    application.links=- url: https://<mycompany>.splunk.com
        title: Splunk
        description: jf
        icon.class: "fa-book"

where:

• <location>:=- url: defines where the link is displayed and the target URL to link to:
  • location can be application.links (Application) or resource.links (Resource). Codefresh does not show Argo CD projects.
  • url is the target URL in the format https://<url>.com, for example, https://codefresh.io.splunk.com.
• titleis the display name for the link, as will appear in the UI. For example, Splunk.
• descriptionis optional, and presents additional info on the link.
• icon-class is optional, and is the font-awesome icon class displayed to the left of the title.

Argo CD also supports if conditional statements to control when the deep links are displayed. When omitted, configured deep links are always displayed.
For more details, read Configuring Deep Links in Argo CD.

Delete GitOps Runtimes

Delete Helm GitOps Runtimes which are offline from the Codefresh platform. The Runtime is not removed from the cluster.

To remove the GitOps Runtime from the Codefresh platform and from the cluster, uninstall the Runtime.

1. In the Codefresh UI, on the toolbar, click the Settings icon.
2. From the sidebar, select GitOps Runtimes.
3. Switch to the List View.
4. To the right of the row with the Runtime to delete, click the context menu and select Delete.
5. Type the name of the Runtime and click Delete to confirm.

Uninstall GitOps Runtimes

Uninstall provisioned GitOps Runtimes that are not in use.

Uninstalling a GitOps Runtime permanently removes:

• The Runtime from the Codefresh platform and from the cluster it is provisioned on
• The Git Sources and managed clusters associated with it

How to

1. In the Codefresh UI, on the toolbar, click the Settings icon.
2. From the sidebar, select GitOps Runtimes.
3. Switch to either the List View or to the Topology View.
4. To uninstall from the List view, do one of the following:
   • To the right of the row with the Runtime to uninstall, click the context menu and select Uninstall.
   • Click the Runtime name, click the context-menu on the top-right, and then select Uninstall.

5. To uninstall from the Topology view, click the Runtime cluster, and from the panel, click the context menu, and then select Uninstall.

6. Copy and run the uninstall command:
   RELEASE_NAME=$(helm ls -n codefresh-gitops-runtime -q) && helm uninstall ${RELEASE_NAME} -n codefresh-gitops-runtime

7. Click Close to exit.

View notifications in Activity Log

The Activity Log is a quick way to monitor notifications for Runtime events such as upgrades. A pull-down panel in the Codefresh toolbar, the Activity Log shows ongoing, success, and error notifications, sorted by date, starting with today’s date.

1. In the Codefresh UI, on the top-right of the toolbar, select Activity Log.
2. To see notifications for provisioned Runtimes, filter by Runtime.

3. To see more information on an error, select the + sign.

Related articles

Monitoring GitOps Runtimes
Managing Git Sources in GitOps Runtimes
Managing external clusters in GitOps Runtimes
Shared Configuration Repository