Change configs

This tutorial shows you how to change a config, validate it, and sync it to a cluster. This tutorial builds on the skills you learned in the quickstart for syncing from a Git repository. Imagine that you are a new member of the compliance team in your organization, modifying your first config.

Before you begin

Before you begin this tutorial, complete the following steps:

  1. Follow the quickstart for syncing from a Git repository, and do not delete the cluster that you configure.

  2. Create a GitHub account if you don't have one.

  3. Follow the instructions for adding a new SSH key to your GitHub account in the GitHub documentation. You need the location of your private key to complete this tutorial.

It's also helpful to be familiar with forking and cloning Git repositories.

Create your repo

In this section, you create a Git repository by creating a fork of the Anthos Config Management samples repository, then create a local clone as your working copy.

To create the repo, complete the following steps:

  1. In your browser, go to the Anthos Config Management samples repository and click Fork.

  2. On your local system, clone your fork:

    git clone git@github.com:GIT_USERNAME/anthos-config-management-samples.git

    Replace GIT_USERNAME with your GitHub username.

  3. Configure your local system to authenticate to GitHub using the SSH key that you added in the Before you begin section.

Create a nomos vet pre-commit hook

The nomos vet command prevents you from committing a config with syntax errors. You can install a pre-commit hook that runs the nomos vet command against your change. With this hook, nomos vet checks for syntax errors and other problems with your changes before you commit to your local repo.

To add the pre-commit hook, complete the following steps:

  1. In a terminal, go to the directory where you cloned your repo.

  2. Edit the .git/hooks/pre-commit file. Notice the . character in the .git/ directory.

  3. nomos vet should run against the quickstart/multirepo/root directory in your locally cloned repo. Set --source-format=unstructured because unstructured is the recommended format for most users and the example in the quickstart is unstructured. Add the following to the file:

    nomos vet --path=REPO_PATH/quickstart/multirepo/root --source-format=unstructured
    

    Replace REPO_PATH with the fully qualified path to where you cloned the repo.

  4. Save the file.

  5. Ensure that the .git/hooks/pre-commit file is executable:

    chmod +x .git/hooks/pre-commit
  6. To test the pre-commit, you can intentionally add a syntax error to a config (such as deleting a : character), before attempting to run git commit . nomos vet runs and shows an error message.

Configure your cluster

Create Kubernetes Secrets for the Git crendentials

  1. Obtain the private key registered with your Git repository. Be mindful about how you download the file and where you store it because it can be used to authenticate to your Git repository.

  2. Create a Secret using an SSH key pair.

    • Create a Secret for the root repository:

      kubectl create secret generic SECRET_NAME \
       --namespace=config-management-system \
       --from-file=ssh=/path/to/KEYPAIR_PRIVATE_KEY_FILENAME
      
    • Create a Secret for each namespace repository:

      The root repository includes a RepoSync object, so you need to create a Secret in the RepoSync object's namespace (gamestore):

      kubectl create secret generic SECRET_NAME \
       --namespace=gamestore
       --from-file=ssh=/path/to/KEYPAIR_PRIVATE_KEY_FILENAME
      

    Replace the following:

    • SECRET_NAME: add the name of the Secret.
    • /path/to/KEYPAIR_PRIVATE_KEY_FILENAME: add the name of the private key (the one without the .pub suffix).
  3. Protect the private key on your local disk, or otherwise delete it.

Update the Git configurations

Edit the Git configurations in the RootSync and RepoSync objects that you created in the quickstart for syncing from a Git repository. Make the following changes:

  1. Update the following values of your RootSync object:

    • Change the value of repo to the address of your fork. Replace GIT_USERNAME with your GitHub username.
    • Change the value of auth to ssh
    • Set spec.git.secretRef.name to SECRET_NAME. The SECRET_NAME Secret should already exist in the cluster.

    The following example shows an updated config:

    apiVersion: configsync.gke.io/v1beta1
    kind: RootSync
    metadata:
      name: root-sync
      namespace: config-management-system
    spec:
      sourceFormat: unstructured
      git:
        repo: git@github.com:GIT_USERNAME/anthos-config-management-samples.git
        branch: main
        dir: quickstart/multirepo/root
        auth: ssh
        secretRef:
          name: SECRET_NAME
    

    Replace SECRET_NAME with the name of the Secret.

    For an explanation of the fields, see ConfigManagement fields.

  2. Apply the configuration to your cluster:

    kubectl apply -f root-sync.yaml
  3. Update the following values of your RepoSync object:

    • Change the value of repo to the address of your fork. Replace GIT_USERNAME with your GitHub username.
    • Change the value of auth to ssh
    • Set spec.git.secretRef.name to SECRET_NAME. The SECRET_NAME Secret should already exist in the cluster.

    The following example shows an updated config:

    apiVersion: configsync.gke.io/v1beta1
    kind: Repo
    metadata:
      name: repo-sync
      namespace: gamestore
    spec:
      sourceFormat: unstructured
      git:
        repo: git@github.com:GIT_USERNAME/anthos-config-management-samples.git
        branch: main
        dir: quickstart/multirepo/namespaces/gamestore
        auth: ssh
        secretRef:
          name: SECRET_NAME
    

    Replace SECRET_NAME with the name of the Secret.

  4. Commit the changes to your root repository:

    git add .
    git commit -m 'Update gamestore RepoSync'
    git push
    

If the commands succeed, Kubernetes updates the Config Management Operator on your cluster to begin syncing your cluster's configuration from the repository. To verify that the Config Management Operator is running, list all Pods running in the config-management-system namespace:

kubectl get pods -n config-management-system

Example output:

NAME                                       READY   STATUS    RESTARTS   AGE
admission-webhook-7dbc55cbf5-9thcj         1/1     Running   0          6d18h
admission-webhook-7dbc55cbf5-pmrxt         1/1     Running   0          6d18h
ns-reconciler-gamestore-67ff4dcbc4-x4vnh   3/3     Running   0          14m
reconciler-manager-7cdb699bf8-8lvll        2/2     Running   0          6d18h
root-reconciler-84f976b74d-mh6zd           3/3     Running   0          14m

At this point, your cluster has the same configs as in the quickstart for syncing from a Git repository. Because your fork has the same contents. You can follow the exercises in that quickstart and see the same results.

Modify a config in the repo

When you create or modify a config in the repo, Config Sync detects the commit and applies the new configuration to relevant Kubernetes objects.

Make additions to a config

In this section, you add user admin@gamestore.com to the gamestore-admin RoleBinding in the gamestore namespace:

  1. Open a terminal and issue the following command to watch the gamestore RoleBinding for changes:

    kubectl get rolebindings gamestore-admin -n gamestore -o yaml --watch
    
  2. Open another terminal and go to the local clone of your repo.

  3. Edit the quickstart/multirepo/root/rolebinding-gamestore-admin.yaml file to add admin@gamestore.com to the subjects field.

    After editing, the file has the following contents:

    kind: RoleBinding
    apiVersion: rbac.authorization.k8s.io/v1
    metadata:
      name: gamestore-admin
      namespace: gamestore
    subjects:
    - kind: ServiceAccount
      name: ns-reconciler-gamestore
      namespace: config-management-system
    - kind: User
      name: admin@gamestore.com
      apiGroup: rbac.authorization.k8s.io
    roleRef:
      kind: ClusterRole
      name: admin
      apiGroup: rbac.authorization.k8s.io
    
  4. Save the file:

    git add quickstart/multirepo/root/rolebinding-gamestore-admin.yaml
    
  5. Create a commit:

    git commit -m "Add admin@gamestore.com to cluster admin"
    
  6. Push the commit to your fork:

    git push origin main
    
  7. Go back to the terminal where you are watching the gamestore-admin object. In a few seconds, the change is synced to the cluster.

Revert changes

Config Sync makes it easier for you to revert changes.

To revert the change you made in the previous section, complete the following steps:

  1. Go back to the terminal you were using for Git.

  2. Use the git log command to find the hash (in this example, it's the top entry)

  3. Revert the latest change:

    git revert HASH
    
    git push origin main
    

    Because a revert operation creates a new commit, nomos vet --source-format=unstructured checks the resulting config again and ensures that the syntax is still correct.

  4. Go back to the terminal where you are watching the gamestore-admin object and notice that admin@gamestore.com is no longer listed in the subjects for the ClusterRole.

  5. Press Control+C to stop watching the gamestore-admin object.

This exercise shows that Config Sync keeps objects in sync with the configs in your repo when you commit changes to the repo.

Clean up

After you finish the exercises in this tutorial, do the following to clean up:

  • Delete the cluster you used for testing.
  • Delete the local clone of your fork.
  • Delete the local private SSH key, if applicable.
  • Delete your fork of the example repo. This action deletes any deploy keys associated only to the repo.

What's next