Writing configs

This quickstart shows you how to write your own config, validate it, and sync it to a cluster. This topic builds on the skills you learned in the quickstart for using a read-only repo. Imagine that you are a new member of the compliance team in your organization, creating your first config.

After you complete this quickstart, you can follow an advanced quickstart about managing and unmanaging existing cluster objects.

Before you begin

Config Sync requires an active Anthos entitlement. For more information, see Pricing for Anthos.

  1. Follow the quickstart for using a read-only repo, and do not delete the cluster.

  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.

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

Create your repo

For this quickstart, create your repo by creating a fork of the foo-corp repo, then creating a local clone as your working copy.

  1. In your browser, go to the foo-corp repo and click the Fork button.

  2. On your local system, clone your fork. Replace [my-git-username] with your github username.

    git clone git@github.com:[my-git-username]/csp-config-management.git
  3. Configure your local system to authenticate to GitHub using the SSH key you added in Before you begin.

Create the nomos vet pre-commit hook

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 or other problems with your changes before you commit to your local repo.

  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 the .git/ directory.

  3. nomos vet should run against the foo-corp directory in your locally cloned repo. Add the following to the file, replacing [/path/to/repo] with the fully-qualified path to where you cloned the repo.

    nomos vet --path=/path/to/repo/foo-corp

    Save the file.

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

    chmod +x .git/hooks/pre-commit
  5. Test the pre-commit with git commit . nomos vet runs and shows an error message.

Configure your cluster

Create the git-creds Secret

  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. Store the private key as a Secret named git-creds in the Kubernetes cluster:

    kubectl create secret generic git-creds \
     --namespace=config-management-system \
  3. Protect the private key on your local disk, or otherwise delete it.

Update the ConfigManagement object

Edit the config-management.yaml file you created in the quickstart for using a read-only repo. Make the following changes:

  1. Update the value of syncRepo to the address of your fork, and replace my-github-username with your GitHub username.
  2. Update the value of secretType to ssh. The git-creds Secret should already exist in the cluster.

The following example shows an updated See the installation instructions for an explanation of the fields.

apiVersion: configmanagement.gke.io/v1
kind: ConfigManagement
  name: config-management
  # clusterName is required and must be unique among all managed clusters
  clusterName: my-cluster
    syncRepo: git@github.com:my-github-username/csp-config-management.git
    syncBranch: 1.0.0
    secretType: ssh
    policyDir: "foo-corp"

Apply the configuration to your cluster.

kubectl apply -f config-management.yaml

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

kubectl get pods -n config-management-system
NAME                                   READY     STATUS    RESTARTS   AGE
git-importer-5f8bdb59bd-7nn5m          2/2       Running   0          2m
monitor-58c48fbc66-ggrmd               1/1       Running   0          2m
syncer-7bbfd7686b-dxb45                1/1       Running   0          2m

At this point, your cluster has exactly the same configs as in the quickstart for using a read-only repo, 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.

In this example, you add user jane@foo-corp.com to the namespace-readers ClusterRoleBinding.

Open a terminal and issue the following command to watch the namespace-readers ClusterRoleBinding for changes:

kubectl get clusterrolebindings namespace-readers -o yaml --watch

Open another terminal and go to the local clone of your repo. Edit the cluster/namespace-reader-clusterrolebinding.yaml file to add jane@foo-corp.com to the subjects field. After editing, the file has these contents:

kind: ClusterRoleBinding
apiVersion: rbac.authorization.k8s.io/v1
  name: namespace-readers
- kind: User
  name: cheryl@foo-corp.com
  apiGroup: rbac.authorization.k8s.io
- kind: User
  name: jane@foo-corp.com
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: namespace-reader
  apiGroup: rbac.authorization.k8s.io

Save the file. Create a commit.

git add cluster/namespace-reader-clusterrolebinding.yaml

git commit -m "Add Jane to namespace-reader"

The nomos vet command runs when you attempt to commit, and prevents you from committing a config with syntax errors. To test this, you can intentionally add a syntax error to the file (such as by deleting a : character), before attempting to commit.

Push the commit to your fork:

git push origin master

Go back to the terminal where you are watching the namespace-reader object. In a few seconds, the change is synced to the cluster.

It's easy to revert a change too. Go back to the terminal you were using for Git. Use the git log command to find the hash (in this example, it is the top entry), and revert it. In the following command, use the hash of the commit where you see [HASH]. Because a revert operation creates a new commit, nomos vet checks the resulting config again.

git revert [HASH]

git push origin master

Go back to the terminal where you are watching the namespace-reader object and notice that jane@foo-corp.com is no longer listed in the subjects for the ClusterRole.

Press Control+C to stop watching the namespace-reader object.

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

Cleaning up

After you finish the exercises in this topic, 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 deletes any deploy keys associated only to the repo.

What's next