feat: add kustomize tooling for custom CS install (#1455)

This provides a new approach for customizing and installing Config Sync
with many of the same features that ConfigManagement provides without
the need to install another operator layer. A subsequent change will add
tooling to package the kustomization file as a release artifact.

Makefile

@@ -90,7 +90,7 @@ OTELCONTRIBCOL_VERSION := v0.103.0-gke.4
 OTELCONTRIBCOL_IMAGE_NAME := gcr.io/config-management-release/otelcontribcol:$(OTELCONTRIBCOL_VERSION)
 
 # Directory used for staging Docker contexts.
-STAGING_DIR := $(OUTPUT_DIR)/staging
+STAGING_DIR ?= $(OUTPUT_DIR)/staging
 
 # Directory used for staging the manifest primitives.
 NOMOS_MANIFEST_STAGING_DIR := $(STAGING_DIR)/operator
@@ -311,9 +311,15 @@ build-status:
 test-unit: buildenv-dirs "$(KUSTOMIZE)"
 	@./scripts/test-unit.sh $(NOMOS_GO_PKG)
 
+# small unit test to verify the behavior of an example kustomization for manual install
+.PHONY: test-kustomization
+test-kustomization:
+	$(MAKE) build-manifests STAGING_DIR=$(OUTPUT_DIR)/testing REGISTRY=gcr.io/cs-test IMAGE_TAG=placeholder
+	@./scripts/test-kustomization.sh
+
 # Runs unit tests and linter.
 .PHONY: test
-test: test-unit lint
+test: test-unit test-kustomization lint
 
 # The presubmits have made side-effects in the past, which makes their
 # validation suspect (as the repository they are validating is different

installation/README.md

@@ -0,0 +1,93 @@
+# Installing Config Sync manually
+
+This document is a guide on how to manually install Config Sync on a Kubernetes
+cluster without Fleet Management.
+
+The recommended approach is to [install Config Sync managed by fleet](https://cloud.google.com/kubernetes-engine/enterprise/config-sync/docs/how-to/installing-config-sync).
+
+This document includes configurations for some common user journeys, but is not
+an exhaustive list of how a Config Sync installation can be customized.
+
+## Pre-requisites
+
+This guide requires the following command line tools:
+
+- [kubectl](https://kubernetes.io/docs/tasks/tools/)
+- [kustomize](https://github.com/kubernetes-sigs/kustomize)
+
+## Uninstall Config Management
+
+**Prerequisites**:
+- Set the kubectl context in your shell to the desired cluster before proceeding.
+- Ensure [hierarchy controller is disabled](https://cloud.google.com/kubernetes-engine/enterprise/config-sync/docs/how-to/migrate-hierarchy-controller#kubectl) before proceeding.
+
+
+If you have previously installed Config Management on your cluster, Config Management
+must first be uninstalled before following this guide to install/upgrade Config Sync.
+
+You can check if Config Management is installed on your cluster with the following command:
+
+```shell
+kubectl get configmanagement
+```
+
+If the output is not empty, Config Management is currently installed on the cluster
+and must be uninstalled before proceeding. To uninstall Config Management, there are
+two options:
+- Use `nomos migrate --remove-configmanagement`
+- Use the [uninstall script](uninstall_configmanagement.sh) provided in this directory.
+
+### Using `nomos migrate`
+
+Install the [nomos CLI](https://cloud.google.com/kubernetes-engine/enterprise/config-sync/docs/how-to/nomos-command)
+of version 1.20.0 or greater. Then run the following command to update the cluster
+in your current kubectl context:
+
+```shell
+nomos migrate --remove-configmanagement
+```
+
+### Using the uninstall shell script
+
+The `nomos` approach is recommended, however a simple shell script is also provided
+as an alternative approach that does not require installing the `nomos` binary.
+The script can be run directly to update the cluster in your current kubectl context:
+
+```shell
+./uninstall_configmanagement.sh
+```
+
+## Install Config Sync
+
+### Rendering the installation manifest
+
+A [kustomization file](kustomization.yaml) is provided in this directory with
+some common use cases commented out. Edit the kustomization file accordingly for
+any desired customizations before installing.
+
+Once the kustomization file is ready, the manifests can be rendered using `kustomize`:
+
+```shell
+kustomize build . > config-sync-install.yaml
+```
+
+The rendered manifests are now written to the `config-sync-install.yaml` file. This
+file may be inspected/reviewed before applying to the cluster.
+
+Optional: If you want Config Sync deployments to use a private registry
+rather than the default registry, the following command can be used to replace
+the image URLs for all deployments:
+
+```shell
+kustomize build . | sed -e "s|gcr.io/config-management-release/|[*REGISTRY*]/|g" > config-sync-install.yaml
+```
+
+### Apply the manifest to the cluster
+
+Once you are ready to apply the manifests to the cluster and install Config Sync,
+the manifests can be applied directly with `kubectl`:
+
+```shell
+kubectl apply -f config-sync-install.yaml
+```
+

installation/kustomization.yaml

@@ -0,0 +1,57 @@
+# Copyright 2024 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+apiVersion: kustomize.config.k8s.io/v1beta1
+kind: Kustomization
+
+resources:
+- CONFIG_SYNC_MANIFEST
+# [WEBHOOK] - To install admission-webhook, uncomment the following line
+#- ADMISSION_WEBHOOK_MANIFEST
+
+patches:
+# [RESOURCES] - To adjust resource requests/limits, uncomment the following section and set the desired resources
+#- patch: |-
+#    - op: add
+#      path: "/spec/template/spec/containers/0/resources"
+#      value:
+#        requests:
+#          cpu: [*CPU_REQUEST*]
+#          memory: [*MEMORY_REQUEST*]
+#        limits:
+#          cpu: [*CPU_LIMIT*]
+#          memory: [*MEMORY_LIMIT*]
+#  target:
+#    kind: Deployment
+#    name: reconciler-manager
+#    namespace: config-management-system
+#
+# [CLUSTER_NAME] - To set cluster name, uncomment the following section and set the desired cluster name
+#- patch: |-
+#    - op: add
+#      path: /spec/template/spec/containers/0/args/-
+#      value: --cluster-name=[*CLUSTER_NAME*]
+#  target:
+#    kind: Deployment
+#    name: reconciler-manager
+#    namespace: config-management-system
+#
+# [LOG_LEVEL] - To set log level, uncomment the following section and set the desired log level
+#- patch: |-
+#    - op: add
+#      path: /spec/template/spec/containers/0/args/-
+#      value: --v=[*VERBOSITY*]
+#  target:
+#    kind: Deployment
+#    name: reconciler-manager
+#    namespace: config-management-system

scripts/license-headers.sh

@@ -26,6 +26,7 @@ cd "${REPO_ROOT}"
 ignores=(
   "-ignore=vendor/**"
   "-ignore=e2e/testdata/helm-charts/**"
+  "-ignore=test/kustomization/expected.yaml"
   "-ignore=.output/**"
   "-ignore=e2e/testdata/*.xml"
   "-ignore=.idea/**"

scripts/test-kustomization.sh

@@ -0,0 +1,22 @@
+#!/bin/bash
+# Copyright 2024 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+set -euo pipefail
+
+REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd -P)"
+
+out=$(kustomize build --load-restrictor=LoadRestrictionsNone "${REPO_ROOT}/test/kustomization" | sed -e "s|gcr.io/cs-test/|example.com/|g")
+
+diff "${REPO_ROOT}/test/kustomization/expected.yaml" <( echo "${out}" )