Merge pull request #61 from cybozu-go/modify-document

Add the maintenance procedure

Author: takahiro-yamada

CHANGELOG.md

@@ -48,28 +48,39 @@ This project adheres to [Semantic Versioning](http://semver.org/).
 
 This release updates the base image and the packages used by rebuilding the image.
 This fixes git vulnerabilities
+
 - USN-5810-1: Git vulnerabilities
 - USN-5810-2: Git regression
 
 ## [0.1.4] - 2022-12-15
+
 ### Fix
+
 - Refer avdc creationTimestamp when next start time is nil (#39)
 - Validate avdc template when startSchedule is not set (#40)
 
 ## [0.1.3] - 2022-10-19
+
 ### Fix
+
 - Replace CMD to ENTRYPOINT in Dockerfile.Runner (#33)
 - Defaulting by controller instead admission webhook (#35)
+
 ### Added
+
 - Add shorthand `avdc` (#34)
 
 ## [0.1.2] - 2022-09-28
+
 ### Fix
+
 - Fix config (#32)
 - Inherit pod metadata of pod_template (#33)
 
 ## [0.1.1] - 2022-09-26
+
 ### Removed
+
 - kube-rbac-proxy is removed (#30)
 
 ## [0.1.0] - 2022-09-16

README.md

@@ -3,18 +3,20 @@
 [![PkgGoDev](https://pkg.go.dev/badge/github.com/cybozu-go/nyamber?tab=overview)](https://pkg.go.dev/github.com/cybozu-go/nyamber?tab=overview)
 [![Go Report Card](https://goreportcard.com/badge/github.com/cybozu-go/nyamber)](https://goreportcard.com/report/github.com/cybozu-go/nyamber)
 
-Nyamber
-============================
+# Nyamber
+
 Nyamber is a custom controller to create Neco environment
 
 ## Features
+
 - Run a dctest in a pod
 - Created a pod which runs dctest and a service to access the pod corresponding to vdc custom resources
 - Run user-defined command
 - Reflect status of executed command in the vdc resource.
 - Create dctest pods on the specified schedule
 
 ## Supported Software
+
 - Kubernetes: 1.28, 1.29, 1.30
 
 ## Documentation

docs/README.md

@@ -1 +1,6 @@
-# Template documentation
+# Nyamber documentation
+
+Nyamber is a custom controller to create Neco environment.
+It is currently developed and maintained by [Cybozu](https://cybozu-global.com/).
+
+The repository is at <https://github.com/cybozu-go/nyamber>.

docs/SUMMARY.md

@@ -1,10 +1,16 @@
 # Summary
 
-[Template](README.md)
+[Nyamber](README.md)
+
+## User manual
 
-# User manual
 [UserManual](user-manual.md)
 
-# Developer documents
+## Developer documents
 
+- [Design notes](design.md)
+- [Development procedure](development.md)
+- Custom Resources
+  - [VirtualDC](crd_virtualdc.md)
+  - [AutoVirtualDC](crd_autovirtualdc.md)
 - [Release procedure](release.md)

docs/design.md

@@ -24,7 +24,6 @@ This is custom resource to automate deployment dctest pod.
 Nyamber create `VirtualDC` custom resource from its definition according to the schedule field.
 You can specify the `VirtualDC` startSchedule and stopSchedule with cron format.
 
-
 ### Kubernetes workloads
 
 #### `virtualdc-controller`
@@ -36,6 +35,7 @@ It create Runner pod which runs dctest and service to access Runner pod.
 
 A deployment that create and delete VirutualDC resources according to set schedules.
 *You can't specify only one schedule. You should specify both schedules or leave both schedules empty*
+
 - startSchedule and stopSchedule are empty: controller create virtualdc immediately
 - startSchedule and stopSchedule are set: calculate NextTime from those schedule and set time to status
   - nextStartTime < now and nextstopTime < now: do nothing

docs/development.md

@@ -3,45 +3,45 @@
 1. Prepare a Linux box running Docker.
 2. Checkout this repository.
 
-    ```console
-    $ git clone https://github.com/cybozu-go/nyamber
+    ```bash
+    git clone https://github.com/cybozu-go/nyamber
     ```
 
 ## Setup CLI tools
 
 1. Install [aqua][].
 
-    https://aquaproj.github.io/docs/tutorial-basics/quick-start
+    <https://aquaproj.github.io/docs/tutorial-basics/quick-start>
 
 2. Install CLI tools.
 
-    ```console
-    $ cd cybozu-go/nyamber
-    $ aqua i -l
+    ```bash
+    cd cybozu-go/nyamber
+    aqua i -l
     ```
 
 ## Development & Debug
 
 1. Launch local Kubernetes cluster.
 
-    ```console
-    $ cd cybozu-go/nyamber
-    $ make start
+    ```bash
+    cd cybozu-go/nyamber
+    make start
     ```
 
 2. Start [Tilt][].
 
-    ```console
-    $ cd cybozu-go/nyamber
-    $ tilt up
+    ```bash
+    cd cybozu-go/nyamber
+    tilt up
     ```
 
-3. Access: http://localhost:10350/
+3. Access: `http://localhost:10350/`
 4. Stop the Kubernetes cluster.
 
-    ```console
-    $ cd cybozu-go/nyamber
-    $ make stop
+    ```bash
+    cd cybozu-go/nyamber
+    make stop
     ```
 
 [aqua]: https://aquaproj.github.io

docs/maintenance.md

@@ -0,0 +1,51 @@
+# Maintenance
+
+## How to update supported Kubernetes
+
+Nyamber supports the three latest Kubernetes versions.
+If a new Kubernetes version is released, please update the followings:
+
+### 1. Update supported kubernetes and dependencies versions
+
+- Kubernetes versions:
+  - `k8s-version` in [.github/workflows/ci.yaml](/.github/workflows/ci.yaml): You can check the available versions at <https://hub.docker.com/r/kindest/node/tags>.
+  - "Supported software" in [README.md](/README.md)
+- Kubernetes tools versions:
+  - Update `KUSTOMIZE_VERSION` in [Makefile](/Makefile) to the latest version from <https://github.com/kubernetes-sigs/kustomize/releases>.
+  - Update `E2ETEST_K8S_VERSION` in [e2e/Makefile](/e2e/Makefile) to the latest supported version of kubernetes.
+- After saving the changes above, update `ENVTEST_K8S_VERSION` in [Makefile](/Makefile) to the latest patch version among the latest supported kubernetes minor versions listed by running `make setup && tmp/bin/setup-envtest list` at the root of this repository. If the latest minor supported version is `1.30.Z`, find `1.30.Z+` from the output but not `1.31.Z`.
+- Run `aqua update` to update tools in [aqua.yaml](/aqua.yaml). Then, manually align the minor versions of kubernetes and kubectl in `aqua.yaml`. If the minor version of `kubernetes/kubectl` in `aqua.yaml` precedes the latest supported minor versions of kubernetes, adjust it to match.  
+  _e.g._, If `kubernetes/kubectl` is `1.31.Z` and the latest supported version is `1.30.Z`, modify `kubernetes/kubectl` version to `1.30.Z`.
+- Other tools versions:
+  - Update `PLACEMAT_VERSION` in [Dockerfile](/Dockerfile) to the latest version from <https://github.com/cybozu-go/placemat/releases>.
+  - Update `CONTROLLER_TOOLS_VERSION` in [Makefile](/Makefile) to the latest version from <https://github.com/kubernetes-sigs/controller-tools/releases>.
+  - Update `CERT_MANAGER_VERSION` in [e2e/Makefile](/e2e/Makefile) to the latest version from <https://github.com/cert-manager/cert-manager/releases>.
+- Other dependencies versions:
+  - Update actions in [.github/workflows/ci.yaml](/.github/workflows/ci.yaml) and [.github/workflows/release.yaml](/.github/workflows/release.yaml)
+  - Update `ghcr.io/cybozu/golang` image and `GO_VERSION` in [Dockerfile](/Dockerfile) and [Dockerfile.runner](/Dockerfile.runner) to the latest version from <https://github.com/cybozu/neco-containers/pkgs/container/golang>.
+- `go.mod` and `go.sum`:
+  - Run `go get -u ./...`.
+
+If Kubernetes or related APIs have changed, please update the relevant source code accordingly.
+
+### 2. Update nyamber by running `make`
+
+You can update nyamber by running the following `make` commands:
+
+```sh
+make setup
+make manifests
+make build
+```
+
+### 3. Fix test code if tests fail
+
+After pushing the change, if the CI fails, fix the tests and push the changes again.
+
+_e.g._, <https://github.com/cybozu-go/nyamber/pull/59>
+
+### 4. Release the new version
+
+After merging the changes above, follow the procedures written in [docs/release.md](/docs/release.md) and release the new version.
+
+_e.g._, <https://github.com/cybozu-go/nyamber/pull/60>

docs/release.md

@@ -1,5 +1,4 @@
-Release procedure
-=================
+# Release procedure
 
 This document describes how to release a new version.
 
@@ -32,42 +31,42 @@ It should look like:
 
 1. Determine a new version number. Then set `VERSION` variable.
 
-    ```console
+    ```bash
     # Set VERSION and confirm it. It should not have "v" prefix.
-    $ VERSION=x.y.z
-    $ echo $VERSION
+    VERSION=x.y.z
+    echo $VERSION
     ```
 
 2. Make a branch to release
 
-    ```console
-    $ git neco dev "bump-$VERSION"
+    ```bash
+    git switch -c "bump-$VERSION"
     ```
 
 3. Edit `CHANGELOG.md` for the new version ([example][]).
 4. Commit the change and push it.
 
-    ```console
-    $ git commit -a -m "Bump version to $VERSION"
-    $ git neco review
+    ```bash
+    git commit -a -m "Bump version to $VERSION"
+    git push origin "bump-$VERSION"
     ```
 
 5. Merge this branch.
 6. Add a git tag to the main HEAD, then push it.
 
-    ```console
+    ```bash
     # Set VERSION again.
-    $ VERSION=x.y.z
-    $ echo $VERSION
+    VERSION=x.y.z
+    echo $VERSION
 
-    $ git checkout main
-    $ git pull
-    $ git tag -a -m "Release v$VERSION" "v$VERSION"
+    git checkout main
+    git pull
+    git tag -a -m "Release v$VERSION" "v$VERSION"
 
     # Make sure the release tag exists.
-    $ git tag -ln | grep $VERSION
+    git tag -ln | grep $VERSION
 
-    $ git push origin "v$VERSION"
+    git push origin "v$VERSION"
     ```
 
 GitHub actions will build and push artifacts such as container images and

docs/user-manual.md

@@ -3,8 +3,10 @@
 ## create VirtualDC Automatically
 
 ### Create AutoVirtualDC Resource
+
 Apply the AutoVirtualDC manifest like this.
-```
+
+```yaml
 apiVersion: nyamber.cybozu.io/v1beta1
 kind: AutoVirtualDC
 metadata:
@@ -20,38 +22,49 @@ spec:
   stopSchedule: "0 1 * * *"
   timeoutDuration: "20m"
 ```
+
 If this manifest is applied, Nyamber creates virtualdc pods at 0:00 every day.
-```
+
+```console
 $ kubectl get pod -n nyamber-pod
 NAME               READY   STATUS    RESTARTS   AGE
 auto-virtual-dc2   1/1     Running   0          4s
 ```
+
 You can access the pod with service
-```
+
+```console
 $ kubectl get service -n nyamber-pod
 NAME               TYPE        CLUSTER-IP      EXTERNAL-IP   PORT(S)   AGE
 auto-virtual-dc2   ClusterIP   10.96.178.115   <none>        80/TCP    21s
 ```
 
 ## create VirtualDC manually
+
 ### Create VirtualDC Resource
+
 Apply the VirtualDC manifest like this.
-```
+
+```yaml
 apiVersion: nyamber.cybozu.io/v1beta1
 kind: VirtualDC
 metadata:
   name: vdc-sample
 spec:
   skipNecoApps: true
 ```
+
 Nyamber create virtualdc pods immediately
-```
+
+```console
 $ kubectl get pod -n nyamber-pod
 NAME         READY   STATUS    RESTARTS   AGE
 vdc-sample   1/1     Running   0          2s
 ```
+
 You can access the pod with service
-```
+
+```console
 $ kubectl get service -n nyamber-pod
 NAME         TYPE        CLUSTER-IP      EXTERNAL-IP   PORT(S)   AGE
 vdc-sample   ClusterIP   10.96.233.168   <none>        80/TCP    13s