From ddedcafaaf8b4064c63a7dbf22c794c15d3892ec Mon Sep 17 00:00:00 2001 From: Murad Biashimov Date: Thu, 27 Jun 2024 12:18:31 +0200 Subject: [PATCH] docs: generate secret commands (#773) --- docs/docs/api-reference/cassandra.md | 25 ++++++++++++ docs/docs/api-reference/clickhouse.md | 22 +++++++++++ docs/docs/api-reference/clickhouseuser.md | 22 +++++++++++ docs/docs/api-reference/grafana.md | 24 ++++++++++++ docs/docs/api-reference/kafka.md | 33 ++++++++++++++++ docs/docs/api-reference/mysql.md | 27 +++++++++++++ docs/docs/api-reference/opensearch.md | 22 +++++++++++ docs/docs/api-reference/postgresql.md | 26 ++++++++++++ docs/docs/api-reference/project.md | 19 +++++++++ docs/docs/api-reference/redis.md | 22 +++++++++++ docs/docs/api-reference/serviceuser.md | 25 ++++++++++++ generators/docs/generator.go | 48 +++++++++++++++++++++-- 12 files changed, 312 insertions(+), 3 deletions(-) diff --git a/docs/docs/api-reference/cassandra.md b/docs/docs/api-reference/cassandra.md index 8b214758..90c281a5 100644 --- a/docs/docs/api-reference/cassandra.md +++ b/docs/docs/api-reference/cassandra.md @@ -58,6 +58,31 @@ Name Project Region Plan State my-cassandra aiven-project-name google-europe-west1 startup-4 RUNNING ``` +To view the details of the `Secret`, use the following command: +```shell +kubectl describe secret cassandra-secret +``` + +You can use the [jq](https://github.com/jqlang/jq) to quickly decode the `Secret`: + +```shell +kubectl get secret cassandra-secret -o json | jq '.data | map_values(@base64d)' +``` + +The output is similar to the following: + +```{ .json .no-copy } +{ + "CASSANDRA_HOST": "", + "CASSANDRA_PORT": "", + "CASSANDRA_USER": "", + "CASSANDRA_PASSWORD": "", + "CASSANDRA_URI": "", + "CASSANDRA_HOSTS": "", + "CASSANDRA_CA_CERT": "", +} +``` + ## Cassandra {: #Cassandra } Cassandra is the Schema for the cassandras API. diff --git a/docs/docs/api-reference/clickhouse.md b/docs/docs/api-reference/clickhouse.md index 0a0fe67f..b15a9358 100644 --- a/docs/docs/api-reference/clickhouse.md +++ b/docs/docs/api-reference/clickhouse.md @@ -58,6 +58,28 @@ Name Project Region Plan State my-clickhouse my-aiven-project google-europe-west1 startup-16 RUNNING ``` +To view the details of the `Secret`, use the following command: +```shell +kubectl describe secret my-clickhouse +``` + +You can use the [jq](https://github.com/jqlang/jq) to quickly decode the `Secret`: + +```shell +kubectl get secret my-clickhouse -o json | jq '.data | map_values(@base64d)' +``` + +The output is similar to the following: + +```{ .json .no-copy } +{ + "CLICKHOUSE_HOST": "", + "CLICKHOUSE_PORT": "", + "CLICKHOUSE_USER": "", + "CLICKHOUSE_PASSWORD": "", +} +``` + ## Clickhouse {: #Clickhouse } Clickhouse is the Schema for the clickhouses API. diff --git a/docs/docs/api-reference/clickhouseuser.md b/docs/docs/api-reference/clickhouseuser.md index 773599b6..14e3abe2 100644 --- a/docs/docs/api-reference/clickhouseuser.md +++ b/docs/docs/api-reference/clickhouseuser.md @@ -60,6 +60,28 @@ Name Username Service Name Project my-clickhouse-user example-username my-clickhouse my-aiven-project ``` +To view the details of the `Secret`, use the following command: +```shell +kubectl describe secret clickhouse-user-secret +``` + +You can use the [jq](https://github.com/jqlang/jq) to quickly decode the `Secret`: + +```shell +kubectl get secret clickhouse-user-secret -o json | jq '.data | map_values(@base64d)' +``` + +The output is similar to the following: + +```{ .json .no-copy } +{ + "CLICKHOUSEUSER_HOST": "", + "CLICKHOUSEUSER_PORT": "", + "CLICKHOUSEUSER_USER": "", + "CLICKHOUSEUSER_PASSWORD": "", +} +``` + ## ClickhouseUser {: #ClickhouseUser } ClickhouseUser is the Schema for the clickhouseusers API. diff --git a/docs/docs/api-reference/grafana.md b/docs/docs/api-reference/grafana.md index b91a8613..543c44dc 100644 --- a/docs/docs/api-reference/grafana.md +++ b/docs/docs/api-reference/grafana.md @@ -57,6 +57,30 @@ Name Project Region Plan State my-grafana my-aiven-project google-europe-west1 startup-1 RUNNING ``` +To view the details of the `Secret`, use the following command: +```shell +kubectl describe secret grafana-secret +``` + +You can use the [jq](https://github.com/jqlang/jq) to quickly decode the `Secret`: + +```shell +kubectl get secret grafana-secret -o json | jq '.data | map_values(@base64d)' +``` + +The output is similar to the following: + +```{ .json .no-copy } +{ + "GRAFANA_HOST": "", + "GRAFANA_PORT": "", + "GRAFANA_USER": "", + "GRAFANA_PASSWORD": "", + "GRAFANA_URI": "", + "GRAFANA_HOSTS": "", +} +``` + ## Grafana {: #Grafana } Grafana is the Schema for the grafanas API. diff --git a/docs/docs/api-reference/kafka.md b/docs/docs/api-reference/kafka.md index f0a686c8..42e04782 100644 --- a/docs/docs/api-reference/kafka.md +++ b/docs/docs/api-reference/kafka.md @@ -49,6 +49,39 @@ Name Project Region Plan State my-kafka my-aiven-project google-europe-west1 startup-2 RUNNING ``` +To view the details of the `Secret`, use the following command: +```shell +kubectl describe secret kafka-secret +``` + +You can use the [jq](https://github.com/jqlang/jq) to quickly decode the `Secret`: + +```shell +kubectl get secret kafka-secret -o json | jq '.data | map_values(@base64d)' +``` + +The output is similar to the following: + +```{ .json .no-copy } +{ + "KAFKA_HOST": "", + "KAFKA_PORT": "", + "KAFKA_USERNAME": "", + "KAFKA_PASSWORD": "", + "KAFKA_ACCESS_CERT": "", + "KAFKA_ACCESS_KEY": "", + "KAFKA_SASL_HOST": "", + "KAFKA_SASL_PORT": "", + "KAFKA_SCHEMA_REGISTRY_HOST": "", + "KAFKA_SCHEMA_REGISTRY_PORT": "", + "KAFKA_CONNECT_HOST": "", + "KAFKA_CONNECT_PORT": "", + "KAFKA_REST_HOST": "", + "KAFKA_REST_PORT": "", + "KAFKA_CA_CERT": "", +} +``` + ## Kafka {: #Kafka } Kafka is the Schema for the kafkas API. diff --git a/docs/docs/api-reference/mysql.md b/docs/docs/api-reference/mysql.md index 6b5810c3..a43e1481 100644 --- a/docs/docs/api-reference/mysql.md +++ b/docs/docs/api-reference/mysql.md @@ -57,6 +57,33 @@ Name Project Region Plan State my-mysql my-aiven-project google-europe-west1 business-4 RUNNING ``` +To view the details of the `Secret`, use the following command: +```shell +kubectl describe secret mysql-secret +``` + +You can use the [jq](https://github.com/jqlang/jq) to quickly decode the `Secret`: + +```shell +kubectl get secret mysql-secret -o json | jq '.data | map_values(@base64d)' +``` + +The output is similar to the following: + +```{ .json .no-copy } +{ + "MYSQL_HOST": "", + "MYSQL_PORT": "", + "MYSQL_DATABASE": "", + "MYSQL_USER": "", + "MYSQL_PASSWORD": "", + "MYSQL_SSL_MODE": "", + "MYSQL_URI": "", + "MYSQL_REPLICA_URI": "", + "MYSQL_CA_CERT": "", +} +``` + ## MySQL {: #MySQL } MySQL is the Schema for the mysqls API. diff --git a/docs/docs/api-reference/opensearch.md b/docs/docs/api-reference/opensearch.md index d6e91939..d19f15e2 100644 --- a/docs/docs/api-reference/opensearch.md +++ b/docs/docs/api-reference/opensearch.md @@ -50,6 +50,28 @@ Name Project Region Plan State my-os my-aiven-project google-europe-west1 startup-4 RUNNING ``` +To view the details of the `Secret`, use the following command: +```shell +kubectl describe secret os-secret +``` + +You can use the [jq](https://github.com/jqlang/jq) to quickly decode the `Secret`: + +```shell +kubectl get secret os-secret -o json | jq '.data | map_values(@base64d)' +``` + +The output is similar to the following: + +```{ .json .no-copy } +{ + "OPENSEARCH_HOST": "", + "OPENSEARCH_PORT": "", + "OPENSEARCH_USER": "", + "OPENSEARCH_PASSWORD": "", +} +``` + ## OpenSearch {: #OpenSearch } OpenSearch is the Schema for the opensearches API. diff --git a/docs/docs/api-reference/postgresql.md b/docs/docs/api-reference/postgresql.md index 2738449b..6e42b5f5 100644 --- a/docs/docs/api-reference/postgresql.md +++ b/docs/docs/api-reference/postgresql.md @@ -52,6 +52,32 @@ Name Project Region Plan State my-postgresql aiven-project-name google-europe-west1 startup-4 RUNNING ``` +To view the details of the `Secret`, use the following command: +```shell +kubectl describe secret postgresql-secret +``` + +You can use the [jq](https://github.com/jqlang/jq) to quickly decode the `Secret`: + +```shell +kubectl get secret postgresql-secret -o json | jq '.data | map_values(@base64d)' +``` + +The output is similar to the following: + +```{ .json .no-copy } +{ + "POSTGRESQL_HOST": "", + "POSTGRESQL_PORT": "", + "POSTGRESQL_DATABASE": "", + "POSTGRESQL_USER": "", + "POSTGRESQL_PASSWORD": "", + "POSTGRESQL_SSLMODE": "", + "POSTGRESQL_DATABASE_URI": "", + "POSTGRESQL_CA_CERT": "", +} +``` + ## PostgreSQL {: #PostgreSQL } PostgreSQL is the Schema for the postgresql API. diff --git a/docs/docs/api-reference/project.md b/docs/docs/api-reference/project.md index 65e7bf00..e8f2ec01 100644 --- a/docs/docs/api-reference/project.md +++ b/docs/docs/api-reference/project.md @@ -48,6 +48,25 @@ Name my-project ``` +To view the details of the `Secret`, use the following command: +```shell +kubectl describe secret project-secret +``` + +You can use the [jq](https://github.com/jqlang/jq) to quickly decode the `Secret`: + +```shell +kubectl get secret project-secret -o json | jq '.data | map_values(@base64d)' +``` + +The output is similar to the following: + +```{ .json .no-copy } +{ + "PROJECT_CA_CERT": "", +} +``` + ## Project {: #Project } Project is the Schema for the projects API. diff --git a/docs/docs/api-reference/redis.md b/docs/docs/api-reference/redis.md index 4617d88b..ab6618ca 100644 --- a/docs/docs/api-reference/redis.md +++ b/docs/docs/api-reference/redis.md @@ -52,6 +52,28 @@ Name Project Region Plan State k8s-redis my-aiven-project google-europe-west1 startup-4 RUNNING ``` +To view the details of the `Secret`, use the following command: +```shell +kubectl describe secret redis-token +``` + +You can use the [jq](https://github.com/jqlang/jq) to quickly decode the `Secret`: + +```shell +kubectl get secret redis-token -o json | jq '.data | map_values(@base64d)' +``` + +The output is similar to the following: + +```{ .json .no-copy } +{ + "REDIS_HOST": "", + "REDIS_PORT": "", + "REDIS_USER": "", + "REDIS_PASSWORD": "", +} +``` + ## Redis {: #Redis } Redis is the Schema for the redis API. diff --git a/docs/docs/api-reference/serviceuser.md b/docs/docs/api-reference/serviceuser.md index 52534457..77caa0d6 100644 --- a/docs/docs/api-reference/serviceuser.md +++ b/docs/docs/api-reference/serviceuser.md @@ -45,6 +45,31 @@ Name Service Name Project my-service-user my-service-name aiven-project-name ``` +To view the details of the `Secret`, use the following command: +```shell +kubectl describe secret service-user-secret +``` + +You can use the [jq](https://github.com/jqlang/jq) to quickly decode the `Secret`: + +```shell +kubectl get secret service-user-secret -o json | jq '.data | map_values(@base64d)' +``` + +The output is similar to the following: + +```{ .json .no-copy } +{ + "SERVICEUSER_HOST": "", + "SERVICEUSER_PORT": "", + "SERVICEUSER_USERNAME": "", + "SERVICEUSER_PASSWORD": "", + "SERVICEUSER_CA_CERT": "", + "SERVICEUSER_ACCESS_CERT": "", + "SERVICEUSER_ACCESS_KEY": "", +} +``` + ## ServiceUser {: #ServiceUser } ServiceUser is the Schema for the serviceusers API. diff --git a/generators/docs/generator.go b/generators/docs/generator.go index b2731078..d5f7901f 100644 --- a/generators/docs/generator.go +++ b/generators/docs/generator.go @@ -17,6 +17,8 @@ const ( maxPatternLength = 42 // minHeaderLevel doesn't let print headers less than minHeaderLevel = 2 + // secretKeysPrefix precede secret keys in the description + secretKeysPrefix = "Exposes secret keys:" ) // reEmptyLines finds multiple newlines @@ -238,7 +240,7 @@ func (s *schemaType) GetDescription() string { // Wraps code chunks with backticks d = reAdmonitions.ReplaceAllString(d, "\n\n!!! $1\n\n $2") - d = strings.ReplaceAll(d, "Exposes secret keys:", "\n!!! note\n\n Exposes secret keys:") + d = strings.ReplaceAll(d, secretKeysPrefix, "\n!!! note\n\n "+secretKeysPrefix) return reInlineCode.ReplaceAllString(d, "`$1`") } @@ -338,8 +340,12 @@ type exampleType struct { Metadata struct { Name string `yaml:"name"` } - Spec map[string]any `yaml:"spec"` - Table []exampleTableColumn + Spec map[string]any `yaml:"spec"` + Table []exampleTableColumn `yaml:"-"` + Secret struct { + Name string + Keys []string + } `yaml:"-"` } // exampleTableColumn columns and values from the exampleType @@ -347,6 +353,8 @@ type exampleTableColumn struct { Title, Value string } +var reExampleSecretKeys = regexp.MustCompile("(?:`)([A-Z_]+)") + // GetExample returns exampleType with formed output table func (s *schemaType) GetExample() *exampleType { var example *exampleType @@ -389,6 +397,16 @@ func (s *schemaType) GetExample() *exampleType { example.Table = append(example.Table, column) } + if secret, ok := example.Spec["connInfoSecretTarget"]; ok { + // The secret's kube name + example.Secret.Name = secret.(map[string]any)["name"].(string) + + // Secret keys + for _, m := range reExampleSecretKeys.FindAllStringSubmatch(s.Description, -1) { + example.Secret.Keys = append(example.Secret.Keys, m[1]) + } + } + return example } @@ -443,6 +461,30 @@ The output is similar to the following: {{ range $example.Table }}{{ rfill .Title .Value }} {{ end }} {{ range $example.Table }}{{ rfill .Value .Title }} {{ end }} {{ backtick 3 }} + +{{ if $example.Secret.Name }} +To view the details of the {{ backtick 1 }}Secret{{ backtick 1 }}, use the following command: +{{ backtick 3 }}shell +kubectl describe secret {{ $example.Secret.Name }} +{{ backtick 3 }} + +You can use the [jq](https://github.com/jqlang/jq) to quickly decode the {{ backtick 1 }}Secret{{ backtick 1 }}: + +{{ backtick 3 }}shell +kubectl get secret {{ $example.Secret.Name }} -o json | jq '.data | map_values(@base64d)' +{{ backtick 3 }} + +The output is similar to the following: + +{{ backtick 3 }}{ .json .no-copy } +{ + {{- range $example.Secret.Keys }} + "{{ . }}": "",{{ end }} +} +{{ backtick 3 }} + +{{ end }} + {{ end }} {{ end }}