docs: update docs for gcp secretmanager (#193)

nakamasato · Apr 5, 2023 · e01a645 · e01a645
1 parent 8fe9cef
commit e01a645
Show file tree

Hide file tree

Showing 6 changed files with 141 additions and 81 deletions.
diff --git a/README.md b/README.md
@@ -127,80 +127,8 @@ This is a go-based Kubernetes operator built with [operator-sdk](https://sdk.ope
 ## With GCP Secret Manager
 
 Instead of writing raw password in `MySQL.Spec.AdminPassword`, you can get the password for root user from an external secret manager (e.g. GCP) (ref: [Authenticate to Google Cloud using a service account](https://cloud.google.com/kubernetes-engine/docs/tutorials/authenticating-to-cloud-platform))
-1. Set var PROJECT_ID
-    ```
-    PROJECT_ID=<your_project_id>
-    gcloud config set project $PROJECT_ID
-    ```
-1. Create Secret for password
-    ```
-    echo -n "password" | gcloud secrets create mysql-password --data-file=-
-    ```
-1. Create service account
-    ```
-    gcloud iam service-accounts create mysql-operator --display-name=mysql-operator
-    ```
-1. Grant permission to the service account
-    ```
-    sa_email=$(gcloud iam service-accounts describe mysql-operator@${PROJECT_ID}.iam.gserviceaccount.com --format='value(email)')
-    gcloud secrets add-iam-policy-binding mysql-password --role=roles/secretmanager.secretAccessor --member=serviceAccount:${sa_email}
-    ```
-1. Generate service account key json.
-    ```
-    gcloud iam service-accounts keys create config/default/sa-private-key.json --iam-account=mysql-operator@${PROJECT_ID}.iam.gserviceaccount.com
-    ```
-1. Update the following in `config/default/kustomization.yaml`
-    ```yaml
-    # [GCP SecretManager] Mount GCP service account key as secret
-    secretGenerator:
-    - name: gcp-sa-private-key
-      files:
-      - sa-private-key.json
-    ```
-
-    ```yaml
-    # [GCP SecretManager] Mount GCP service account key as secret
-    - manager_gcp_sa_secret_patch.yaml
-    ```
-1. Run
-    ```
-    skaffold dev
-    ```
-1. Create custom resources
-
-    Update `config/samples-with-k8s/mysql_v1alpha1_mysql.yaml` with `gcp_secret_name`:
-
-    ```yaml
-    apiVersion: mysql.nakamasato.com/v1alpha1
-    kind: MySQL
-    metadata:
-      name: mysql-sample
-    spec:
-      host: mysql.default # need to include namespace if you use Kubernetes Service as an endpoint.
-      admin_user:
-        name: root
-        type: raw
-      admin_password:
-        name: mysql-password # echo -n "password" | gcloud secrets create mysql-password --data-file=-
-        type: gcp
-    ```
-
-    ```
-    kubectl apply -k config/samples-wtih-k8s
-    ```
-
-1. Check
-
-    ```
-    kubectl get -k config/samples-on-k8s
-    NAME                                      HOST            ADMINUSER   USERCOUNT
-    mysql.mysql.nakamasato.com/mysql-sample   mysql.default   root        1
-
-    NAME                                        MYSQLUSER   SECRET   PHASE   REASON
-    mysqluser.mysql.nakamasato.com/nakamasato   true        true     Ready   Both secret and mysql user are successfully created.
-    ```
 
-For more details, read [Workload Identity](https://cloud.google.com/kubernetes-engine/docs/concepts/workload-identity)
+[Read credentials from GCP SecretManager](docs/usage/gcp-secretmanager.md)
 
 ## Exposed Metrics
 

diff --git a/docs/developer-guide/api-resources.md b/docs/developer-guide/api-resources.md
@@ -9,25 +9,40 @@
 MySQL represents a MySQL cluster with root acess.
 
 - Spec
-    - adminUser
+    - AdminUser
     - AdminPassword
 - Status
     - UserCount
+    - DBCount
 
 TODO:
 
-1. Credential management.
-1. Change to `ClusterResource` so `MySQLUser` in any namespace can reference it. (No need of changing `OwnerReference`)
+- [x] Credential management. ([#190 GCP SecretManager](https://github.com/nakamasato/mysql-operator/pull/190))
+- [ ] Change to `ClusterResource` so `MySQLUser` in any namespace can reference it. (No need of changing `OwnerReference`)
+
     > Namespaced dependents can specify cluster-scoped or namespaced owners.
+    Ref: [Owner references in object specifications](https://kubernetes.io/docs/concepts/overview/working-with-objects/owners-dependents/#owner-references-in-object-specifications)
 
 ## `MySQLUser`
 
 When `MySQLUser` is created/edited/deleted, MySQL user will be created/edited/deleted by the controller.
 
 - Spec
-    - MysqlName
-    - Host
+    - MysqlName: The name of `MySQL` object
+    - Host: MySQL user's host
 - Status
     - Conditions
-    - Phase
-    - Reason
+    - Phase: `Ready` if Secret and MySQL user are created, otherwise `NotReady`
+    - Reason: Reason for `NotReady`
+
+## `MySQLDB`
+
+You can create MySQL database with this custom resource.
+
+- Spec
+    - DBName: The database name. (The reason for not directly using the object's name is becase some object name can't be used for database name)
+    - MysqlName: The name of `MySQL` object
+
+ToDo:
+
+- [ ] Validate `DBName`
diff --git a/docs/developer-guide/reconciliation.md b/docs/developer-guide/reconciliation.md
@@ -1,4 +1,4 @@
-# Reconciliation Loop
+# Reconciliation Loop (Old)
 
 ![](reconciliation.drawio.svg)
 

diff --git a/docs/index.md b/docs/index.md
@@ -10,6 +10,8 @@
     - [Reconciliation](developer-guide/reconciliation.md)
     - [API Resource](developer-guide/api-resources.md)
     - [Debug](developer-guide/debug.md)
+- Usage
+    - [GCP SecretManager](usage/gcp-secretmanager.md)
 
 ## Getting Started
 

diff --git a/docs/usage/gcp-secretmanager.md b/docs/usage/gcp-secretmanager.md
@@ -0,0 +1,110 @@
+# Read credentials from GCP SecretManager
+
+mysql-operator can get the credentials of the MySQL user (which is used to access to the target MySQL cluster) from [GCP SecretManager](https://cloud.google.com/secret-manager)
+
+## Prepare GCP resources
+
+1. Set var PROJECT_ID
+    ```
+    PROJECT_ID=<your_project_id>
+    gcloud config set project $PROJECT_ID
+    ```
+1. Create Secret `mysql-password` with value `password`
+    ```
+    echo -n "password" | gcloud secrets create mysql-password --data-file=-
+    ```
+1. Create service account `mysql-operator`
+    ```
+    gcloud iam service-accounts create mysql-operator --display-name=mysql-operator
+    ```
+1. Grant permission to the service account
+    ```
+    sa_email=$(gcloud iam service-accounts describe mysql-operator@${PROJECT_ID}.iam.gserviceaccount.com --format='value(email)')
+    gcloud secrets add-iam-policy-binding mysql-password --role=roles/secretmanager.secretAccessor --member=serviceAccount:${sa_email}
+    ```
+1. Generate service account key json.
+    ```
+    gcloud iam service-accounts keys create config/default/sa-private-key.json --iam-account=mysql-operator@${PROJECT_ID}.iam.gserviceaccount.com
+    ```
+
+## Prepare mysql-operator yaml
+
+1. Uncomment the following piece of codes in `config/default/kustomization.yaml`
+    ```yaml
+    # [GCP SecretManager] Mount GCP service account key as secret
+    secretGenerator:
+    - name: gcp-sa-private-key
+      files:
+      - sa-private-key.json
+    ```
+
+    ```yaml
+    # [GCP SecretManager] Mount GCP service account key as secret
+    - manager_gcp_sa_secret_patch.yaml
+    ```
+
+    <details><summary>config/default/kustomization.yaml</summary>
+
+    ```yaml
+    namespace: mysql-operator-system
+    namePrefix: mysql-operator-
+
+    bases:
+    - ../crd
+    - ../rbac
+    - ../manager
+
+    # [GCP SecretManager] Mount GCP service account key as secret
+    secretGenerator:
+    - name: gcp-sa-private-key
+      files:
+      - sa-private-key.json
+
+    patchesStrategicMerge:
+    # [GCP SecretManager] Mount GCP service account key as secret
+    - manager_gcp_sa_secret_patch.yaml
+    ```
+
+    </details>
+
+## Run
+
+1. Run
+    ```
+    skaffold dev
+    ```
+1. Create custom resources
+
+    Update `admin_password` with `type: gcp` in `config/samples-with-k8s/mysql_v1alpha1_mysql.yaml`:
+
+    ```yaml
+    apiVersion: mysql.nakamasato.com/v1alpha1
+    kind: MySQL
+    metadata:
+      name: mysql-sample
+    spec:
+      host: mysql.default # need to include namespace if you use Kubernetes Service as an endpoint.
+      admin_user:
+        name: root
+        type: raw
+      admin_password:
+        name: mysql-password # echo -n "password" | gcloud secrets create mysql-password --data-file=-
+        type: gcp
+    ```
+
+    ```
+    kubectl apply -k config/samples-wtih-k8s
+    ```
+
+1. Check
+
+    ```
+    kubectl get -k config/samples-on-k8s
+    NAME                                      HOST            ADMINUSER   USERCOUNT
+    mysql.mysql.nakamasato.com/mysql-sample   mysql.default   root        1
+
+    NAME                                        MYSQLUSER   SECRET   PHASE   REASON
+    mysqluser.mysql.nakamasato.com/nakamasato   true        true     Ready   Both secret and mysql user are successfully created.
+    ```
+
+For more details, read [Workload Identity](https://cloud.google.com/kubernetes-engine/docs/concepts/workload-identity)
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -17,10 +17,15 @@ extra:
     property: G-9NTB93RVPJ
 markdown_extensions:
   - pymdownx.superfences
+  - pymdownx.magiclink
+  - pymdownx.tasklist:
+      custom_checkbox: true
 nav:
   - Home: 'index.md'
   - 'Developer Guide':
     - 'API Resources': 'developer-guide/api-resources.md'
     - 'Reconciliation': 'developer-guide/reconciliation.md'
     - 'Testing': 'developer-guide/testing.md'
     - 'Debug': 'developer-guide/debug.md'
+  - Usage:
+    - 'GCP SecretManager': usage/gcp-secretmanager.md