1# GCP Config Connector
2
3Config Connector is a Kubernetes add-on that allows customers to manage GCP
4resources, such as Cloud Spanner or Cloud Storage, through your cluster's API.
5
6With Config Connector, now you can describe GCP resources declaratively using
7Kubernetes-style configuration. Config Connector will create any new GCP
8resources and update any existing ones to the state specified by your
9configuration, and continuously makes sure GCP is kept in sync. The same
10resource model is the basis of Istio, Knative, Kubernetes, and the Google Cloud
11Services Platform.
12
13As a result, developers can manage their whole application, including both its
14Kubernetes components as well as any GCP dependencies, using the same
15configuration, and -- more importantly -- *tooling*. For example, the same
16customization or templating tool can be used to manage test vs. production
17versions of an application across both Kubernetes and GCP.
18
19This repository contains full Config Connector source code. This inlcudes
20controllers, CRDs, install bundles, and sample resource configurations.
21
22## Usage
23
24See https://cloud.google.com/config-connector/docs/overview.
25
26For simple starter examples, see the
27[Resource reference](https://cloud.google.com/config-connector/docs/reference/overview)
28and
29[Cloud Foundation Toolkit Config Connector Solutions](https://github.com/GoogleCloudPlatform/cloud-foundation-toolkit/tree/master/config-connector/solutions).
30
31## Building Config Connector
32
33### Recommended Operating System
34
35- Ubuntu (18.04/20.04)
36- Debian (9/10/11)
37
38### Software requirements
39
40- [go 1.19+]
41- [git]
42- [make]
43- [jq]
44- [kubebuilder 2.3.1]
45- [kustomize 3.5.4]
46- [kube-apiserver 1.21.0]
47
48### Set up your environment
49
50#### Option 1: Set up an environment in a fresh VM (recommended)
51
521. Create an Ubuntu 20.04
53 [VM](https://cloud.google.com/compute/docs/create-linux-vm-instance) on
54 Google Cloud.
55
561. Open an SSH connection to the VM.
57
581. Create a new directory for GoogleCloudPlatform open source projects if it
59 does not exist.
60
61 ```shell
62 mkdir -p ~/go/src/github.com/GoogleCloudPlatform
63 ```
64
651. Update apt and install build-essential.
66
67 ```shell
68 sudo apt-get update
69 sudo apt install build-essential
70 ```
71
721. Clone the source code.
73
74 ```shell
75 cd ~/go/src/github.com/GoogleCloudPlatform
76 git clone https://github.com/GoogleCloudPlatform/k8s-config-connector
77 ```
78
791. Change to environment-setup directory.
80
81 ```shell
82 cd ~/go/src/github.com/GoogleCloudPlatform/k8s-config-connector/scripts/environment-setup
83 ```
84
851. Set up sudoless Docker.
86
87 ```shell
88 ./docker-setup.sh
89 ```
90
911. Exit your current session, then SSH back in to the VM. Then run the
92 following to ensure you have set up sudoless docker correctly:
93
94 ```shell
95 docker run hello-world
96 ```
97
981. Install Golang.
99
100 ```shell
101 cd ~/go/src/github.com/GoogleCloudPlatform/k8s-config-connector/scripts/environment-setup
102 ./golang-setup.sh
103 source ~/.profile
104 ```
105
1061. Install other build dependencies.
107
108 ```shell
109 ./repo-setup.sh
110 source ~/.profile
111 ```
112
1131. Set up a GKE cluster for testing purposes.
114
115 NOTE: `gcp-setup.sh` assumes the VM you are running it from is in a GCP
116 project which does not already have a GKE cluster with Config Connector
117 already set up.
118
119 ```shell
120 ./gcp-setup.sh
121 ```
122
123#### Option 2: Set up an environment manually yourself
124
1251. Install all [required dependencies](#software-requirements)
126
1271. Add all required dependencies to your `$PATH`.
128
1291. Set up a [GOPATH](http://golang.org/doc/code.html#GOPATH).
130
1311. Add `$GOPATH/bin` to your `$PATH`.
132
1331. Clone the repository:
134
135 ```shell
136 cd $GOPATH/src/github.com/GoogleCloudPlatform
137 git clone https://github.com/GoogleCloudPlatform/k8s-config-connector
138 ```
139
140### Build the source code
141
1421. Enter the source code directory:
143
144 ```shell
145 cd $GOPATH/src/github.com/GoogleCloudPlatform/k8s-config-connector
146 ```
147
1481. Build the controller:
149
150 ```shell
151 make manager
152 ```
153
1541. Build the CRDs:
155
156 ```shell
157 make manifests
158 ```
159
1601. Build the config-connector CLI tool:
161
162 ```shell
163 make config-connector
164 ```
165
166### Create a Resource
167
1681. Enable Artifact Registry for your project.
169
170 ```shell
171 gcloud services enable artifactregistry.googleapis.com
172 ```
173
1741. Create a Docker repository. You may need to wait ~10-15 minutes to let
175 your cluster get set up after running `make deploy`.
176
177 ```shell
178 cd $GOPATH/src/github.com/GoogleCloudPlatform/k8s-config-connector
179 kubectl apply -f config/samples/resources/artifactregistryrepository/artifactregistry_v1beta1_artifactregistryrepository.yaml
180 ```
181
1821. Wait a few minutes and then make sure your repository exists in GCP.
183
184 ```shell
185 gcloud artifacts repositories list
186 ```
187
188 If you see a repository, then your cluster is properly functioning and
189 actuating K8s resources onto GCP.
190
191### Make a Code Change
192
193At this point, your cluster is running a CNRM Controller Manager image built on
194your system. Let's make a code change to verify that you are ready to start
195development.
196
1971. Edit
198 $GOPATH/src/github.com/GoogleCloudPlatform/k8s-config-connector/cmd/manager/main.go.
199 Insert the `log.Printf(...)` statement below on the first line of the
200 `main()` function.
201
202 ```shell
203 package manager
204
205 func main() {
206 log.Printf("I have finished the getting started guide.")
207 ...
208 }
209 ```
210
2111. Build and deploy your change, force a pull of the container image.
212
213 ```shell
214 make deploy-controller && kubectl delete pods --namespace cnrm-system --all
215 ```
216
2171. Verify your new log statement is on the first line of the logs for the CNRM
218 Controller Manager pod.
219
220 ```shell
221 kubectl --namespace cnrm-system logs cnrm-controller-manager-0
222 ```
223
224## Contributing to Config Connector
225
226Please refer to our [contribution guide] for more details.
227
228[go 1.19+]: https://go.dev/doc/install
229[git]: https://docs.github.com/en/get-started/quickstart/set-up-git
230[make]: https://www.gnu.org/software/make/
231[jq]: https://stedolan.github.io/jq/
232[kubebuilder 2.3.1]: https://github.com/kubernetes-sigs/kubebuilder/releases/tag/v2.3.1
233[kustomize 3.5.4]: https://github.com/kubernetes-sigs/kustomize/releases/tag/kustomize%2Fv3.5.4
234[kube-apiserver 1.21.0]: https://dl.k8s.io/v1.21.0/bin/linux/amd64/kube-apiserver
235[contribution guide]: CONTRIBUTING.md
View as plain text