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.

   Note: You need the location of your private key to complete this Quickstart.

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 [e-mail]:[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.

Note: Pre-commit hooks are not committed to the repo, and must be configured on each system where you clone the repo. You can commit the files to a different location in the repo and ask your users to copy them to the correct location on their local systems.

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 \
    --from-file=ssh=/path/to/[KEYPAIR-PRIVATE-KEY-FILENAME]
   

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
metadata:
  name: config-management
spec:
  # clusterName is required and must be unique among all managed clusters
  clusterName: my-cluster
  git:
    syncRepo: [e-mail]: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 [e-mail] 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 [e-mail] to the subjects field. After editing, the file has these contents:

kind: ClusterRoleBinding
apiVersion: rbac.authorization.k8s.io/v1
metadata:
  name: namespace-readers
subjects:
- kind: User
  name: [e-mail]
  apiGroup: rbac.authorization.k8s.io
- kind: User
  name: [e-mail]
  apiGroup: rbac.authorization.k8s.io
roleRef:
  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

Note: We recommend that you implement a code-review process, such as using a pull request, rather than pushing changes directly to your repo.

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 [e-mail] 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

• Work through the advanced quickstart about managing and unmanaging cluster objects.
• Learn more about writing configs.
• Learn about validating configs.