From b320c2372fe1e7289c6b68a85d48e1dfb3abb2c2 Mon Sep 17 00:00:00 2001 From: takahiro-yamada Date: Tue, 29 Oct 2024 09:04:50 +0000 Subject: [PATCH 1/5] Standardize markdown syntax --- CHANGELOG.md | 11 +++++++++++ README.md | 6 ++++-- docs/README.md | 7 ++++++- docs/SUMMARY.md | 12 +++++++++--- docs/design.md | 2 +- docs/development.md | 32 ++++++++++++++++---------------- docs/release.md | 35 +++++++++++++++++------------------ docs/user-manual.md | 25 +++++++++++++++++++------ 8 files changed, 83 insertions(+), 47 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 272a445..6f92523 100644 --- a/CHANGELOG.md +++ b/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 diff --git a/README.md b/README.md index c663350..28a077c 100644 --- a/README.md +++ b/README.md @@ -3,11 +3,12 @@ [![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 @@ -15,6 +16,7 @@ Nyamber is a custom controller to create Neco environment - Create dctest pods on the specified schedule ## Supported Software + - Kubernetes: 1.28, 1.29, 1.30 ## Documentation diff --git a/docs/README.md b/docs/README.md index 04953d3..f78265a 100644 --- a/docs/README.md +++ b/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 . diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index fbbdd04..0329968 100644 --- a/docs/SUMMARY.md +++ b/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) diff --git a/docs/design.md b/docs/design.md index edc3ce2..e9db7dc 100644 --- a/docs/design.md +++ b/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 diff --git a/docs/development.md b/docs/development.md index 40784ce..f105f81 100644 --- a/docs/development.md +++ b/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 + 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 diff --git a/docs/release.md b/docs/release.md index 66c8810..4fc27a3 100644 --- a/docs/release.md +++ b/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 neco dev "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 neco review ``` 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 diff --git a/docs/user-manual.md b/docs/user-manual.md index 18aac8f..189a22f 100644 --- a/docs/user-manual.md +++ b/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,23 +22,30 @@ 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 80/TCP 21s ``` ## create VirtualDC manually + ### Create VirtualDC Resource + Apply the VirtualDC manifest like this. -``` + +```yaml apiVersion: nyamber.cybozu.io/v1beta1 kind: VirtualDC metadata: @@ -44,14 +53,18 @@ metadata: 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 80/TCP 13s From 047ee99149037b54cb146f8814fd935829d39c5f Mon Sep 17 00:00:00 2001 From: takahiro-yamada Date: Tue, 29 Oct 2024 09:17:22 +0000 Subject: [PATCH 2/5] Replace `git neco` --- docs/release.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/release.md b/docs/release.md index 4fc27a3..15826e1 100644 --- a/docs/release.md +++ b/docs/release.md @@ -40,7 +40,7 @@ It should look like: 2. Make a branch to release ```bash - git neco dev "bump-$VERSION" + git switch -c "bump-$VERSION" ``` 3. Edit `CHANGELOG.md` for the new version ([example][]). @@ -48,7 +48,7 @@ It should look like: ```bash git commit -a -m "Bump version to $VERSION" - git neco review + git push origin "bump-$VERSION" ``` 5. Merge this branch. From e297493267ce009e09e75d9bb9491b59b21400a1 Mon Sep 17 00:00:00 2001 From: takahiro-yamada Date: Thu, 31 Oct 2024 05:35:06 +0000 Subject: [PATCH 3/5] Add the maintenance procedure --- docs/maintenance.md | 51 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 51 insertions(+) create mode 100644 docs/maintenance.md diff --git a/docs/maintenance.md b/docs/maintenance.md new file mode 100644 index 0000000..66cc1f6 --- /dev/null +++ b/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: You can check the available versions at . + - `k8s-version` in [.github/workflows/ci.yaml](/.github/workflows/ci.yaml) + - "Supported software" in [README.md](/README.md) +- Kubernetes tools versions: + - Update `KUSTOMIZE_VERSION` in [Makefile](/Makefile) to the latest version from . + - 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 . + - Update `CONTROLLER_TOOLS_VERSION` in [Makefile](/Makefile) to the latest version from . + - Update `CERT_MANAGER_VERSION` in [e2e/Makefile](/e2e/Makefile) to the latest version from . +- 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 . +- `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._, + +### 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._, From ad12a4d4a0579548571e9907dae903b1dfc60d5d Mon Sep 17 00:00:00 2001 From: takahiro-yamada <62680551+takahiro-yamada@users.noreply.github.com> Date: Thu, 31 Oct 2024 18:51:11 +0900 Subject: [PATCH 4/5] Update docs/maintenance.md Co-authored-by: rkwmt <59764959+rkwmt@users.noreply.github.com> --- docs/maintenance.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/maintenance.md b/docs/maintenance.md index 66cc1f6..e722ff5 100644 --- a/docs/maintenance.md +++ b/docs/maintenance.md @@ -7,7 +7,8 @@ If a new Kubernetes version is released, please update the followings: ### 1. Update supported kubernetes and dependencies versions -- Kubernetes versions: You can check the available versions at . +- Kubernetes versions: + - `k8s-version` in [.github/workflows/ci.yaml](/.github/workflows/ci.yaml): You can check the available versions at . - `k8s-version` in [.github/workflows/ci.yaml](/.github/workflows/ci.yaml) - "Supported software" in [README.md](/README.md) - Kubernetes tools versions: From 5698e8ee6f642bce628fc5fd62da1255ff124e61 Mon Sep 17 00:00:00 2001 From: takahiro-yamada Date: Thu, 31 Oct 2024 09:58:35 +0000 Subject: [PATCH 5/5] Fix double description --- docs/maintenance.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/maintenance.md b/docs/maintenance.md index e722ff5..e0262b8 100644 --- a/docs/maintenance.md +++ b/docs/maintenance.md @@ -9,7 +9,6 @@ If a new Kubernetes version is released, please update the followings: - Kubernetes versions: - `k8s-version` in [.github/workflows/ci.yaml](/.github/workflows/ci.yaml): You can check the available versions at . - - `k8s-version` in [.github/workflows/ci.yaml](/.github/workflows/ci.yaml) - "Supported software" in [README.md](/README.md) - Kubernetes tools versions: - Update `KUSTOMIZE_VERSION` in [Makefile](/Makefile) to the latest version from .