Managing GitOps configurations

Create a configuration to deploy apps from your GitHub or GitLab repository to your clusters.

Satellite Config reinforces the current configuration every 5 minutes, whether successful or not. If any update is made to the configuration in the cluster, for example by using kubectl edit, Satellite Config will reinforce the configuration to match what is defined in the GitHub or GitLab repository.

Creating Satellite configurations

With Satellite Config, you create a configuration to specify what Kubernetes resources you want to deploy to a group of Red Hat OpenShift on IBM Cloud clusters that run in your Satellite location or in IBM Cloud.

Before you begin

Make sure that you have the required permissions and that Satellite Config can access your clusters. For more information, see Checking user permissions.
Review the key concepts for Satellite Config.
If you want to use a private repository, you must create a secret on the target cluster that contains a personal access token with at least read access to your private repository.

Creating a secret for using a private repository

To connect to private repositories, you must create and apply a git personal access token to your clusters.

Create a Github or Gitlab token.
- For Github, create a personal access token. When you create the token, grant it repo scope so that it can read from private repositories. You can also create a machine user and bind your personal access token to the machine user.
- For Gitlab, create a personal token or create a deploy token.

Encode the token to base64.

printf "TOKEN_FROM_GITHUB_OR_GITLAB" | base64

For each cluster that you want to use, log in to the cluster and create a secret named razee-git in the razeedeploy namespace by applying the following YAML file:
```
apiVersion: v1
data:
  token: [BASE64_ENCODED_TOKEN_FROM_GITHUB_OR_GITLAB]
kind: Secret
metadata:
  name: razee-git
  namespace: razeedeploy
type: Opaque
```
You can have only one secret between GitHub and GitLab repositories.

Creating Satellite configurations from the console

To deploy an example app, see Deploying Kubernetes resources to clusters with Satellite Config.

To create your custom configuration, use the Satellite UI and follow these steps.

Log in to the Satellite Config UI with your IBM Cloud credentials.
Click Create configuration.
On the Browse templates page, select the GitOps template.

On the Configuration page, specify your configuration name and provider.

Configuration screen fields
Field	Description
Configuration name	Enter the name of the Satellite configuration.
Provider	Select the remote provider for the Satellite configurations, which stores the definitions of Kubernetes resources to be deployed to your clusters. Options are `GitHub` and `GitLab`.

On the Subscription page, specify your repository URL, repository visibility, Git ref details, path to your file or directory, and cluster group to deploy to.

Subscription screen fields
Field	Description
Repository URL	Enter the remote repository to use for this Satellite subscription.
Repository visibility	Select whether this repository is public or private.
Git ref type	Select the type of Git ref to use for this Satellite subscription. Valid values are `Branch`, `Tag`, `Commit`, and `Release`.
Branch/Tag/Commit/Release name	Enter the Git ref to use for this Satellite subscription.
Path	Enter the path to the files in the remote repository to use for this Satellite subscription.
Subscription name	Enter a name for your Satellite subscription. The branch/tag/commit/release name is auto filled as the subscription name by default.
Cluster group	Enter the name of the cluster group where you want to deploy your Kubernetes resources.

On the Summary page, confirm that the displayed information is correct and then click Complete.

Creating Satellite configurations from the CLI

Use the CLI plug-in for Satellite commands to create a configuration.

To create the configuration:

Set up your clusters to use with Satellite Config. This setup includes creating a cluster group and granting Satellite Config access to your clusters.

Create a Satellite configuration.

ibmcloud sat config create --name <config_name> [--provider <provider>] [-q]

Understanding this command's components
Component	Description
`--name <config_name>`	Enter the name of the Satellite configuration.
`--provider <provider>`	Enter remote provider for the Satellite configurations, which stores the definitions of Kubernetes resources to be deployed to your clusters. Valid values are `github` and `gitlab`.
`-q`	Do not show the message of the day or update reminders.

Example output

Creating configuration...
OK
Configuration <config_name> was successfully created with ID 116fffde-0835-467c-8987-67dd42e4e393.

Create a Subscription for your cluster group to the Satellite configuration.

ibmcloud sat subscription create --name <subscription_name> --group <cluster_group_name> --config <config_name_or_ID> --repository <repository_value> --gitref-type <type_value> --gitref <gitref_value> --path <path_value> [-q]

Understanding this command's components
Component	Description
`--name <subscription_name>`	Enter a name for your Satellite subscription.
`--group <cluster_group_name>`	Enter the name of the cluster group where you want to deploy your Kubernetes resources.
`--config <config_name_or_ID>`	Enter the name or ID of the Satellite configuration that you created earlier.
`--repository <repository_value>`	Enter the remote repository to use for this Satellite subscription.
`--gitref-type <type_value>`	Enter the type of Git ref to use for this Satellite subscription. Valid values are `branch`, `commit`, `tag`, and `release`.
`--gitref <gitref_value>`	Enter the Git ref to use for this Satellite subscription.
`--path <path_value>`	Enter the path to the files in the remote repository to use for this Satellite subscription.
`-q`	Do not show the message of the day or update reminders.

Example output

Creating subscription...
OK
Subscription <subscription_name> was successfully created with ID f6114bd5-f71e-4335-b034-ca45fa3cab81.

Follow step 5 in Creating Satellite configurations from the console to review the rollout status of your Kubernetes resources.

Updating your Satellite configuration

To update your configuration, you can make updates on subscription level. The actions you need to take depends on what kind of updates you want to make.

To deploy a new version of your application to the same cluster group, update the files in the GitHub or GitLab repository defined in your configuration and commit the changes.
To change any properties of your source repository, you can edit the subscription and update the fields with new details.
To associate multiple repositories with the same configuration, add a new source repository, or add new Git ref details for the same source repository, you can create new subscriptions. Click Create subscription and fill in the details of your new subscription. If you want to create a new subscription that only has a few details changed, you can use the Duplicate option to auto fill all the fields with properties of the existing subscription and modify the fields that you want to change.
To delete a subscription, use the Remove option.

Updating your subscription from the console

Use the Satellite console to update your configuration.

Log in to the Satellite Config UI with your IBM Cloud credentials.
Select the configuration you want to update.
Click the overflow menu in the line of the subscription to update and select Edit.
On the Edit subscription page, make the changes and click Save.

Updating your Satellite Config with the CLI

Use the CLI plug-in for Satellite commands to update your configuration. If you want to update your configuration to use a new file, you can update your subscription to point to the new file.

Update the Subscription for your cluster group to use the new Satellite configuration in the remote repository. You only need specify the parameters you want to change.

ibmcloud sat subscription update --subscription <subscription_name> [--name <new_subscription_name>] [--group <cluster_group_name>] [--repository <repository_value>] [--gitref-type <type_value>] [--gitref <gitref_value>] [--path <path_value>] [-f] [-q]

Understanding this command's components
Component	Description
`--subscription <subscription_value>`	Enter the name or ID of the subscription to update.
`--name <new_subscription_name>`	Enter the new name of the subscription.
`--group <cluster_group_name>`	Enter the name of the cluster group where you want to deploy your Kubernetes resources.
`--repository <repository_value>`	Enter the remote repository to use for this Satellite subscription.
`--gitref-type <type_value>`	Enter the type of Git ref to use for this Satellite subscription. Valid values are `branch`, `commit`, `tag`, and `release`.
`--gitref <gitref_value>`	Enter the Git ref to use for this Satellite subscription.
`--path <path_value>`	Enter the path to the files in the remote repository to use for this Satellite subscription.
`-f`	Force the command to run without user prompts.
`-q`	Do not show the message of the day or update reminders.

Example output

Are you sure you want to update the subscription <subscription_name>? [y/N]y
OK
Subscription f6114bd5-f71e-4335-b034-ca45fa3cab81 was successfully updated.

Follow step 5 in Creating Satellite configurations from the console to review the rollout status of your Kubernetes resources.