Manage provisioned runtimes

The Runtimes page displays the provisioned runtimes in your account, both hybrid, and the hosted runtime if you have one.

View runtime components and information in List or Topology view formats, and upgrade, uninstall, and migrate runtimes.

Select the view mode to view runtime components and information, and manage provisioned runtimes in the view mode that suits you.

Manage provisioned runtimes:

• Update Git tokens for runtimes
• Configure SSH for runtimes
• Add managed clusters to hybrid or hosted runtimes
• Add and manage Git Sources associated with hybrid or hosted runtimes
• Reset shared configuration repository
• Upgrade provisioned hybrid runtimes
• Upgrade Codefresh CLI
• Uninstall provisioned runtimes
• Update Git tokens for runtimes

Unless specified otherwise, management options are common to both hybrid and hosted runtimes. If an option is valid only for hybrid runtimes, it is indicated as such.

To monitor provisioned hybrid runtimes, including recovering runtimes for failed clusters, see Monitor provisioned hybrid runtimes.

Runtime views

View provisioned hybrid and hosted runtimes in List or Topology view formats.

• List view: The default view, displays the list of provisioned runtimes, the clusters managed by them, and Git Sources.
• Topology view: Displays a hierarchical view of runtimes and the clusters managed by them, with health and sync status of each cluster.

List view

The List view is a grid-view of the provisioned runtimes.

Here is an example of the List view for runtimes.

Here is a description of the information in the List View.

List View Item	Description
Name	The name of the provisioned Codefresh runtime.
Type	The type of runtime provisioned, and can be Hybrid or Hosted.
Cluster/Namespace	The K8s API server endpoint, as well as the namespace with the cluster.
Modules	The modules installed based on the type of provisioned runtime. Hybrid runtimes include CI and CD Ops modules. Hosted runtimes include CD Ops.
Managed Cluster	The number of managed clusters if any, for the runtime. To view list of managed clusters, select the runtime, and then the Managed Clusters tab. To work with managed clusters, see Adding external clusters to runtimes.
Version	The version of the runtime currently installed. Update Available! indicates there are later versions of the runtime. To see all the commits to the runtime, mouse over Update Available!, and select View Complete Change Log.
Last Updated	The most recent update information from the runtime to the Codefresh platform. Updates are sent to the platform typically every few minutes. Longer update intervals may indicate networking issues.
Sync Status	The health and sync status of the runtime or cluster. indicates health or sync errors in the runtime, or a managed cluster if one was added to the runtime. The runtime name is colored red. indicates that the runtime is being synced to the cluster on which it is provisioned.

Topology view

A hierarchical visualization of the provisioned runtimes. The Topology view makes it easy to identify key information such as version, health and sync status, for both the provisioned runtime and the clusters managed by it.
Here is an example of the Topology view for runtimes.

Here is a description of the information in the Topology view.

Topology View Item	Description
Runtime	the provisioned runtime. Hybrid runtimes display the name of the K8s API server endpoint with the cluster. Hosted runtimes display ‘hosted’.
Cluster	The local, and managed clusters if any, for the runtime. indicates the local cluster, always displayed as `in-cluster`. The in-cluster server URL is always set to `https://kubernetes.default.svc/`. indicates a managed cluster. select to add a new managed cluster. To view cluster components, select the cluster. To add and work with managed clusters, see Adding external clusters to runtimes.
Health/Sync status	The health and sync status of the runtime or cluster. indicates health or sync errors in the runtime, or a managed cluster if one was added to the runtime. The runtime or cluster node is bordered in red and the name is colored red. indicates that the runtime is being synced to the cluster on which it is provisioned.
Search and View options	Find a runtime or its clusters by typing part of the runtime/cluster name, and then navigate to the entries found. Topology view options: Resize to window, zoom in, zoom out, full screen view.

Update Git tokens for runtimes

Provisioned runtimes require valid Git tokens at all times to authenticate Git actions by you as a user.

These tokens are specific to the user, and the same token can be used for multiple runtimes.

There are two different situations when you need to update Git tokens:

• Update 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 valid tokens: Optional. You may want to update Git tokens, even valid ones, by deleting the existing token and replacing it with a new token.

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 personal access token in your Git provider account with the correct scopes

Before you begin

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

How to

1. Do one of the following:
   • If you see a notification in the Codefresh UI about invalid runtime tokens, click [Update Token]. The Runtimes page shows runtimes with invalid tokens prefixed by the key icon. Mouse over shows invalid token.
   • To update an existing token, go to Runtimes.
2. From the List view, select the runtime for which to update the Git token.
3. From the context menu with the additional actions at the top-right, select Update Git Runtime Credentials.

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

5. For OAuth2 authorization:

   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.

6. For Git token authentication, expand Advanced authorization options, and then paste the generated token in the Git runtime token field.

7. Click Update Credentials.

Configure SSH for runtimes

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

When SSH is configured for a 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
• GitLab
• Bitbucket
• Azure

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

How to

1. In the Codefresh UI, make sure you are in Runtimes.
2. From the List View, select the runtime for which to configure SSH.
3. From the context menu with the additional actions at 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.

Reset shared configuration repository

Codefresh creates the shared configuration repository when you install the first hybrid or hosted GitOps runtime for your account, and uses it for all runtimes you add to the same account.

If needed, you can reset the location of the shared configuration repository in your account and re-initialize it. For example, when moving from evaluation to production.
Uninstall all the existing runtimes in your account, and then run the reset command. On the next installation, Codefresh re-initializes the shared configuration repo.

Reset shared configuration repo is supported from CLI v0.1.18 and higher.

Before you begin
Uninstall every runtime in the account

How to

• Run:
  cf config --reset-shared-config-repo

Upgrade Codefresh CLI

The Codefresh CLI automatically self-checks its version, and if a newer version is available, prints a banner with the notification.

You can upgrade to a specific version if you so require, or download the latest version to an output folder to upgrade at your convenience.

• Do any of the following:
  • To upgrade to the latest version, run:
    cf upgrade
  • To upgrade to a specific version, even an older version, run:
    cf upgrade --version v<version-number>
    where:
    <version-number> is the version you want to upgrade to.
  • To download the latest version to an output file, run:
    cf upgrade --version v<version-number> -o <output-file>
    where:
    <output-file> is the path to the destination file, for example, /cli-download.

(Hybrid) Upgrade provisioned runtimes

Upgrade provisioned hybrid runtimes to install critical security updates or to install the latest version of all components. Upgrade a provisioned hybrid runtime by running a silent upgrade or through the CLI wizard.
If you have managed clusters for the hybrid runtime, upgrading the runtime automatically updates runtime components within the managed cluster as well.

When there are security updates, the UI displays the alert, At least one runtime requires a security update. The Version column displays an Update Required! notification.

If you have older runtime versions, upgrade to manually define or create the shared configuration repo for your account. See Shared configuration repo.

Before you begin
For both silent or CLI-wizard based upgrades, make sure you have:

• The latest version of the Codefresh CLI
  
• A valid Git token with the required scopes

Silent upgrade

• Pass the mandatory flags in the upgrade command:

  cf runtime upgrade <runtime-name> --git-token <git-token> --silent where:
  <git-token> is a valid runtime token with the repo and admin-repo.hook scopes.

CLI wizard-based upgrade

1. In the Codefresh UI, make sure you are in Runtimes.
2. Switch to either the List View or to the Topology View.
3. List view:
   • Select the runtime name.
   • To see all the commits to the runtime, in the Version column, mouse over Update Available!, and select View Complete Change Log.
   • On the top-right, select Upgrade.

Topology view:
Select the runtime cluster, and from the panel, select the three dots and then select Upgrade Runtime.

4. If you have already installed the Codefresh CLI, in the Install Upgrades panel, copy the upgrade command.

5. In your terminal, paste the command, and do the following:
   • Update the Git token value.
   • To manually define the shared configuration repo, add the --shared-config-repo flag with the path to the repo.
6. Confirm to start the upgrade.

Uninstall provisioned runtimes

Uninstall provisioned hybrid and hosted runtimes that are not in use. Uninstall a runtime by running a silent uninstall, or through the CLI wizard.

Uninstalling a runtime removes the Git Sources and managed clusters associated with the runtime.

Before you begin
For both types of uninstalls, make sure you have:

• The latest version of the Codefresh CLI
• A valid runtime Git token
• The Kube context from which to uninstall the provisioned runtime

Silent uninstall
Pass the mandatory flags in the uninstall command:
cf runtime uninstall <runtime-name> --git-token <git-token> --silent
where:
--git-token is a valid runtime token with the repo and admin-repo.hook scopes.

CLI wizard uninstall

1. In the Codefresh UI, make sure you are in Runtimes.
2. Switch to either the List View or to the Topology View.
3. List view: On the top-right, select the three dots and then select Uninstall.

Topology view: Select the runtime node, and from the panel, select the three dots and then select Uninstall Runtime.

4. If you already have the latest version of the Codefresh CLI, in the Uninstall Codefresh Runtime panel, copy the uninstall command.

5. In your terminal, paste the command, and update the Git token value.
6. Select the Kube context from which to uninstall the runtime, and then confirm the uninstall.
7. If you get errors, run the uninstall command again, with the --force flag.

Related articles

Monitor provisioned hybrid runtimes
Add Git Sources to runtimes
Add external clusters to runtimes