Severity
Minor (nice to have)
Priority
P3 (lowest)
Relevant page(s)
https://redhat-documentation.github.io/supplementary-style-guide/#explain-commands-variables-in-code-blocks
Describe the proposed change
Example AsciiDoc: A definition list explaining user-replaced values
$ cat <<EOF | oc -n <my_product_namespace> create -f -
apiVersion: v1
kind: Secret
metadata:
name: <my_product_database_certificates_secrets>
type: Opaque
stringData:
postgres-ca.pem: |-
-----BEGIN CERTIFICATE-----
<ca_certificate_key>
postgres-key.key: |-
-----BEGIN CERTIFICATE-----
<tls_private_key>
postgres-crt.pem: |-
-----BEGIN CERTIFICATE-----
<tls_certificate_key>
# ...
EOF
where:
<my_product_database_certificates_secrets>
Specifies the name of the certificate secret.
<ca_certificate_key>
Specifies the CA certificate key.
Proposed change:
where:
metadata.name
Specifies the name of the certificate secret.
stringData.postgres-ca.pem
Specifies the CA certificate key.
Why is this change needed?
If the value placeholders are not self-explanatory (for example, Boolean values), the user must read the yaml and try to figure out which key goes with which value.
Using the key instead of the placeholder would make the explanations much easier to scan.
Example:
[source,yaml]
----
apiVersion: v1
kind: ConfigMap
metadata:
name: libvirt-podvm-image-cm
namespace: openshift-sandboxed-containers-operator
data:
PODVM_DISTRO: "rhel"
DOWNLOAD_SOURCES: "<yes_or_no>"
CAA_SRC: "<caa_source_url>"
CAA_REF: "<caa_branch_or_tag>"
CONFIDENTIAL_COMPUTE_ENABLED: "yes"
UPDATE_PEERPODS_CM: "yes"
ORG_ID: "<rhel_organization_id>"
ACTIVATION_KEY: "<rhel_activation_key>"
PODVM_IMAGE_URI: "<image_uri>"
SE_BOOT: "<true_or_false>"
BASE_OS_VERSION: "<rhel_image_os_version>"
SE_VERIFY: "<true_or_false>"
----
+
where:
+
`<yes_or_no>`:: Specify `yes` to use the custom Cloud API Adaptor source to build the pod VM image.
`<caa_source_url>`:: Optional: Specify the URL of the Cloud API Adaptor custom image. The default is \`https://github.com/confidential-containers/cloud-api-adaptor`.
`<caa_branch_or_tag>`:: Optional: Specify the branch or tag of the Cloud API Adaptor custom image. The default is `main`.
`<rhel_activation_key>`:: Specify your {rhel} activation key.
`<image_uri>`:: Optional: If you created a custom peer pod VM image, specify the URI in the format `oci::<image_repo_url>:<image_tag>::<image_path>` (default image path: `/image/podvm.qcow2`). Otherwise, set the value to `""`.
`<true_or_false>` (SE_BOOT):: The default value, `true`, enables IBM Secure Execution for the default Operator-built image. If you use a custom peer pod VM image, set it to `false`.
`<rhel_image_os_version>`:: Specify the {rhel} image operating system version. {ibm-z} Secure Execution supports {rhel} 10.1 and later versions.
`<true_or_false>` (SE_VERIFY):: Specify `false` if you do not want to verify Secure Execution with the digicert CA certificate. The default value is `true`.
Additional context
No response
Severity
Minor (nice to have)
Priority
P3 (lowest)
Relevant page(s)
https://redhat-documentation.github.io/supplementary-style-guide/#explain-commands-variables-in-code-blocks
Describe the proposed change
Example AsciiDoc: A definition list explaining user-replaced values
Proposed change:
Why is this change needed?
If the value placeholders are not self-explanatory (for example, Boolean values), the user must read the yaml and try to figure out which key goes with which value.
Using the key instead of the placeholder would make the explanations much easier to scan.
Example:
Additional context
No response