Edit sample YAML config for easier importing to web docs (#442)

* Edit sample YAML config for easier importing to web docs

* Fix oops

server-config.yaml

@@ -1,5 +1,5 @@
 # The config file version. Currently this field is optional but future
-# KES versions will require it. The only valid value is "v1". 
+# KES versions will require it. The only valid value is "v1".
 version: v1
 
 # The TCP address (ip:port) for the KES server to listen on.
@@ -9,7 +9,7 @@ admin:
   # The admin identity identifies the public/private key pair
   # that can perform any API operation.
   # The admin account can be disabled by setting a value that
-  # cannot match any public key - e.g. "foobar" or "disabled".
+  # cannot match any public key - for example, "foobar" or "disabled".
   identity: c84cc9b91ae2399b043da7eca616048d4b4200edf2ff418d8af3835911db945d
 
 # The TLS configuration for the KES server. A KES server
@@ -25,13 +25,13 @@ tls:
   # by clients. Valid values are "on" and "off". Defaults to off, which
   # is recommended for most use cases.
   auth:     ""
-  
+
   # An optional path to a file or directory containing X.509 certificate(s).
   # If set, the certificate(s) get added to the list of CA certificates for
   # verifying the mTLS certificates sent by the KES clients.
   #
   # If empty, the system root CAs will be used.
-  ca:       ""        
+  ca:       ""
 
   # The TLS proxy configuration. A TLS proxy, like nginx, sits in
   # between a KES client and the KES server and usually acts as a
@@ -59,12 +59,11 @@ tls:
 # The API configuration. The APIs exposed by the KES server can
 # be adjusted here. Each API is identified by its API path.
 #
-# In general, the KES server uses sane defaults for all APIs.
+# In general, the KES server uses reasonable defaults for all APIs.
 # Only customize the APIs if there is a real need.
-# 
-# Disabling authentication for an API must be carefully evaluated.
-# One example, when disabling authentication may be justified, would
-# be the liveness and readiness probes in a Kubernetes environment.
+#
+# An example of when you might disable authentication could be to
+# allow the liveness and readiness probes in a Kubernetes environment.
 #
 # When authentication is disabled, the particular API can be
 # accessed by any client that can send HTTPS requests to the
@@ -75,12 +74,12 @@ tls:
 # a client sends a client certificate during the handshake or KES
 # aborts the handshake. This means that a client can only send an
 # HTTP request to KES when it provides a certificate during the
-# handshake. This is no longer the case when authentication is 
+# handshake. This is no longer the case when authentication is
 # disabled for at least one API. Clients should be able to call
 # the API even without a certificate. Hence, KES can no longer
 # require a certificate during the TLS handshake but instead has
-# to check the certificate when executing the API handler. 
-# 
+# to check the certificate when executing the API handler.
+#
 # Now, these two behaviors have slightly different semantics:
 # By default, KES does not accept connections from clients without
 # a TLS certificate. When disabling authentication for one API, KES
@@ -100,15 +99,15 @@ api:
   /v1/ready:
     skip_auth: false
     timeout:   15s
-    
+
 # The (pre-defined) policy definitions.
 #
 # A policy must have an unique name (e.g my-app) and specifies which
 # server APIs can be accessed. An API path pattern is a glob pattern
 # of the following form:
 #   <API-version>/<API>/<operation>/[<argument-0>/<argument-1>/...]>
 #
-# Each KES server API has an unique path - e.g. /v1/key/create/<key-name>.
+# Each KES server API has an unique path - for example, /v1/key/create/<key-name>.
 # A client request is allowed if and only if no deny pattern AND at least one
 # allow pattern matches the request URL path.
 #
@@ -164,7 +163,7 @@ cache:
     # are discarded.
     # It determines how long the KES server can serve stateless
     # requests when the KMS key store has become unavailable -
-    # e.g. due to a network outage.
+    # for example, due to a network outage.
     #
     # If not set, KES will disable the offline cache.
     #
@@ -190,7 +189,7 @@ log:
   # Logging audit events to STDOUT may flood your console since
   # there will be one audit log event per request-response pair.
   #
-  # For tracing/monitoring audit logs take a look at the
+  # For tracing/monitoring audit logs, see the
   # /v1/log/audit/trace API.
   #
   # Each audit event is a JSON object representing a request-response
@@ -215,13 +214,13 @@ log:
 # In the keys section, pre-defined keys can be specified. The KES
 # server will try to create the listed keys before startup.
 keys:
-  - name: some-key-name 
+  - name: some-key-name
   - name: another-key-name
 
 # The keystore section specifies which KMS - or in general key store - is
 # used to store and fetch encryption keys.
 # A KES server can only use one KMS / key store at the same time.
-# If no store is explicitly specified the server will use store
+# If no store is explicitly specified, the server will store
 # keys in-memory. In this case all keys are lost when the KES server
 # restarts.
 keystore:
@@ -233,56 +232,56 @@ keystore:
   # and development. It should not be used for production.
   fs:
     path: "" # Path to directory. Keys will be stored as files.
-    
+
   # Hashicorp Vault configuration. The KES server will store/fetch
   # secret keys at/from Vault's key-value backend.
   #
-  # For more information take a look at:
+  # For more information, see:
   # https://www.vaultproject.io/api/secret/kv/kv-v1.html
   vault:
-    endpoint: ""  # The Vault endpoint - e.g. https://127.0.0.1:8200
-    engine: ""    # The path of the K/V engine - e.g. secrets. If empty, defaults to: kv. (Vault default)
+    endpoint: ""  # The Vault endpoint - for example, https://127.0.0.1:8200
+    engine: ""    # The path of the K/V engine - for example, secrets. If empty, defaults to: kv. (Vault default)
     version: ""   # The K/V engine version - either "v1" or "v2". The "v1" engine is recommended.
     namespace: "" # An optional Vault namespace. See: https://www.vaultproject.io/docs/enterprise/namespaces/index.html
     prefix: ""    # An optional K/V prefix. The server will store keys under this prefix.
     transit:      # Optionally encrypt keys stored on the K/V engine with a Vault-managed key.
-      engine: ""  # The path of the transit engine - e.g. "my-transit". If empty, defaults to: transit (Vault default)
+      engine: ""  # The path of the transit engine - for example, "my-transit". If empty, defaults to: transit (Vault default)
       key: ""     # The key name that should be used to encrypt entries stored on the K/V engine.
     approle:    # AppRole credentials. See: https://www.vaultproject.io/docs/auth/approle.html
-      namespace: "" # Optional Vault namespace used just for authentication. A single "/" is an alias for the Vault root namespace.
-      engine: ""    # The path of the AppRole engine - e.g. authenticate. If empty, defaults to: approle. (Vault default)
+      namespace: "" # Optional Vault namespace used only for authentication. For the Vault root namespace, use "/".
+      engine: ""    # The path to the AppRole engine, for example: authenticate. If empty, defaults to: approle. (Vault default)
       id: ""        # Your AppRole Role ID
       secret: ""    # Your AppRole Secret ID
     kubernetes: # Kubernetes credentials. See: https://www.vaultproject.io/docs/auth/kubernetes
-      namespace: "" # Optional Vault namespace used just for authentication. A single "/" is an alias for the Vault root namespace.
-      engine: ""    # The path of the Kubernetes engine e.g. authenticate. If empty, defaults to: kubernetes. (Vault default)
+      namespace: "" # Optional Vault namespace used only for authentication. For the Vault root namespace, use "/".
+      engine: ""    # The path of the Kubernetes engine for example, authenticate. If empty, defaults to: kubernetes. (Vault default)
       role: ""      # The Kubernetes JWT role
       jwt:  ""      # Either the JWT provided by K8S or a path to a K8S secret containing the JWT.
     tls:        # The Vault client TLS configuration for mTLS authentication and certificate verification
       key: ""     # Path to the TLS client private key for mTLS authentication to Vault
       cert: ""    # Path to the TLS client certificate for mTLS authentication to Vault
-      ca: ""      # Path to one or multiple PEM root CA certificates
+      ca: ""      # Path to one or more PEM root CA certificates
     status:     # Vault status configuration. The server will periodically reach out to Vault to check its status.
       ping: 10s   # Duration until the server checks Vault's status again.
 
   fortanix:
     # The Fortanix SDKMS key store. The server will store secret keys at the Fortanix SDKMS.
     # See: https://www.fortanix.com/products/data-security-manager/key-management-service
-    sdkms: 
+    sdkms:
       endpoint: ""   # The Fortanix SDKMS endpoint - for example: https://sdkms.fortanix.com
       group_id: ""   # An optional group ID newly created keys will be placed at. For example: ce08d547-2a82-411e-ae2d-83655a4b7617 
-                     # If empty, the applications default group is used. 
+                     # If empty, the applications default group is used.
       credentials:   # The Fortanix SDKMS access credentials
         key: ""      # The application's API key - for example: NWMyMWZlNzktZDRmZS00NDFhLWFjMzMtNjZmY2U0Y2ViMThhOnJWQlh0M1lZaDcxZC1NNnh4OGV2MWNQSDVVSEt1eXEyaURqMHRrRU1pZDg=
       tls:           # The KeySecure client TLS configuration
-        ca: ""       # Path to one or multiple PEM-encoded CA certificates for verifying the Fortanix SDKMS TLS certificate. 
+        ca: ""       # Path to one or more PEM-encoded CA certificates for verifying the Fortanix SDKMS TLS certificate. 
   aws:
     # The AWS SecretsManager key store. The server will store
     # secret keys at the AWS SecretsManager encrypted with
     # AWS-KMS. See: https://aws.amazon.com/secrets-manager
     secretsmanager:
-      endpoint: ""   # The AWS SecretsManager endpoint      - e.g.: secretsmanager.us-east-2.amazonaws.com
-      region: ""     # The AWS region of the SecretsManager - e.g.: us-east-2
+      endpoint: ""   # The AWS SecretsManager endpoint - for example,: secretsmanager.us-east-2.amazonaws.com
+      region: ""     # The AWS region of the SecretsManager - for example,: us-east-2
       kmskey: ""     # The AWS-KMS key ID used to en/decrypt secrets at the SecretsManager. By default (if not set) the default AWS-KMS key will be used.
       credentials:   # The AWS credentials for accessing secrets at the AWS SecretsManager.
         accesskey: ""  # Your AWS Access Key
@@ -293,17 +292,17 @@ keystore:
     # The Gemalto KeySecure key store. The server will store
     # keys as secrets on the KeySecure instance.
     keysecure:
-      endpoint: ""    # The KeySecure endpoint - e.g. https://127.0.0.1
+      endpoint: ""    # The KeySecure endpoint - for example, https://127.0.0.1
       credentials:    # The authentication to access the KeySecure instance.
         token: ""     # The refresh token to obtain new short-lived authentication tokens.
         domain: ""    # The KeySecure domain for which the refresh token is valid. If empty, defaults to the root domain.
         retry: 15s    # The time the KES server waits before it tries to re-authenticate after connection loss.
       tls:            # The KeySecure client TLS configuration
-        ca: ""        # Path to one or multiple PEM-encoded CA certificates for verifying the KeySecure TLS certificate.
+        ca: ""        # Path to one or more PEM-encoded CA certificates for verifying the KeySecure TLS certificate.
 
   gcp:
     # The Google Cloud Platform secret manager.
-    # For more information take a look at:
+    # For more information, see:
     # https://cloud.google.com/secret-manager
     secretmanager:
       # The project ID is a unique, user-assigned ID that can be used by Google APIs.
@@ -315,46 +314,47 @@ keystore:
       endpoint: ""
       # An optional list of GCP OAuth2 scopes. For a list of GCP scopes refer to: https://developers.google.com/identity/protocols/oauth2/scopes
       # If not set, the GCP default scopes are used.
-      scopes: 
+      scopes:
       - ""
       # The credentials for your GCP service account. If running inside GCP (app engine) the credentials
       # can be empty and will be fetched from the app engine environment automatically.
       credentials:
-        client_email:   "" # The service account email                          - e.g. <account>@<project-ID>.iam.gserviceaccount.com
-        client_id:      "" # The service account client ID                      - e.g. 113491952745362495489"
-        private_key_id: "" # The service account private key                    - e.g. 381514ebd3cf45a64ca8adc561f0ce28fca5ec06
-        private_key:    "" # The raw encoded private key of the service account - e.g "-----BEGIN PRIVATE KEY-----\n ... \n-----END PRIVATE KEY-----\n
+        client_email:   "" # The service account email       - for example, <account>@<project-ID>.iam.gserviceaccount.com
+        client_id:      "" # The service account client ID   - for example, 113491952745362495489"
+        private_key_id: "" # The service account private key - for example, 381514ebd3cf45a64ca8adc561f0ce28fca5ec06
+        private_key:    "" # The raw encoded private key of the service account -
+	                   #   for example, "-----BEGIN PRIVATE KEY-----\n ... \n-----END PRIVATE KEY-----\n
 
   azure:
     # The Azure KeyVault configuration.
-    # For more information take a look at:
+    # For more information, see:
     # https://azure.microsoft.com/services/key-vault
     keyvault:
-      endpoint: ""      # The KeyVault endpoint - e.g. https://my-instance.vault.azure.net
+      endpoint: ""         # The KeyVault endpoint - for example, https://my-instance.vault.azure.net
       # Azure client credentials used to
       # authenticate to Azure KeyVault.
       credentials:
-        tenant_id: ""      # The ID of the tenant the client belongs to - i.e. a UUID.
-        client_id: ""      # The ID of the client - i.e. a UUID.
+        tenant_id: ""      # The ID of the tenant the client belongs to - that is, a UUID.
+        client_id: ""      # The ID of the client - that is, a UUID.
         client_secret: ""  # The value of the client secret.
       # Azure managed identity used to
       # authenticate to Azure KeyVault
       # with Azure managed credentials.
       managed_identity:
-        client_id: ""      # The Azure managed identity of the client - i.e. a UUID.
+        client_id: ""      # The Azure managed identity of the client - that is, a UUID.
 
   entrust:
     # The Entrust KeyControl configuration.
-    # For more information take a look at:
+    # For more information, see:
     # https://www.entrust.com/digital-security/key-management/keycontrol
     keycontrol:
-      endpoint: ""     # The KeyControl endpoint - e.g. https://keycontrol.my-org.com
-      vault_id: ""     # The Vault ID            - e.g. e30497c1-bff7-4e81-beb7-fb35c4b7410c
-      box_id:   ""     # The Box name or ID      - e.g. tenant-1
+      endpoint: ""     # The KeyControl endpoint - for example, https://keycontrol.my-org.com
+      vault_id: ""     # The Vault ID            - for example, e30497c1-bff7-4e81-beb7-fb35c4b7410c
+      box_id:   ""     # The Box name or ID      - for example, tenant-1
       # The KeyControl access credentials
       credentials:
-        username: ""   # The username able to access the Vault and Box.
+        username: ""   # A username with access to the Vault and Box.
         password: ""   # The user password
       # The KeyControl client TLS configuration
       tls:
-        ca: ""         # Path to one or multiple PEM-encoded CA certificates for verifying the KeyControl TLS certificate.
+        ca: ""         # Path to one or more PEM-encoded CA certificates for verifying the KeyControl TLS certificate.