Update documentation

Author: AdrianPadilla

kubernetes/samples/scripts/rest/README.md

@@ -2,35 +2,36 @@
 
 When a user enables the operator's external REST API (by setting
 `externalRestEnabled` to `true` when installing the operator Helm chart), the user needs
-to provide the certificate and private key for the API's SSL identity (by setting
-`externalOperatorCert` and `externalOperatorKey` to the base64 encoded PEM of the cert and
-key when installing the operator Helm chart).
+to provide the certificate and private key for api's SSL identity too (by creating a
+`tls secret` before the installation of the operator helm chart).
 
 This sample script generates a self-signed certificate and private key that can be used
-for the operator's external REST API when experimenting with the operator.  They should
+for the operator's external REST api when experimenting with the operator.  They should
 not be used in a production environment.
 
 The syntax of the script is:
 ```
-$ kubernetes/samples/scripts/generate-external-rest-identity.sh <subject alternative names>
+$ kubernetes/samples/scripts/rest/generate-external-rest-identity.sh <SANs> -n <namespace> [-s <secret-name> ]
 ```
 
-Where `<subject alternative names>` lists the subject alternative names to put into the generated
-self-signed certificate for the external WebLogic Operator REST HTTPS interface.  Each must be prefaced
+Where `<SANs>` lists the subject alternative names to put into the generated self-signed 
+certificate for the external WebLogic Operator REST HTTPS interface, <namespace> should match
+the namespace where the operator will be installed, and optionally the secret name, which defaults
+to `weblogic-operator-external-rest-identity`.  Each must be prefaced
 by `DNS:` (for a name) or `IP:` (for an address), for example:
 ```
-DNS:myhost,DNS:localhost,IP:127.0.0.1
+DNS:myhost,DNS:localhost,IP:127.0.0.1 -n weblogic-operator
 ```
 
 You should include the addresses of all masters and load balancers in this list.  The certificate
 cannot be conveniently changed after installation of the operator.
 
-The script prints out the base64 encoded PEM of the generated certificate and private key
-in the same format that the operator Helm chart's `values.yaml` requires.
+The script creates the secret in the weblogic-operator namespace with the self-signed 
+certificate and private key
 
 Example usage:
 ```
-$  generate-external-rest-identity.sh IP:127.0.0.1 > my_values.yaml
+$  generate-external-rest-identity.sh IP:127.0.0.1 -n weblogic-operator > my_values.yaml
 $  echo "externalRestEnabled: true" >> my_values.yaml
    ...
 $  helm install kubernetes/charts/weblogic-operator --name my_operator --namespace my_operator-ns --values my_values.yaml --wait

kubernetes/samples/scripts/rest/generate-external-rest-identity.sh

@@ -12,15 +12,19 @@
 # not be used in a production environment.
 #
 # The sytax of the script is:
-#   kubernetes/samples/scripts/rest/generate-external-rest-identity.sh <SANs> <-n namespace>
 #
-# <subject alternative names> lists the subject alternative names to put into the generated
-# self-signed certificate for the external WebLogic Operator REST https interface.
-# For example:
+#   kubernetes/samples/scripts/rest/generate-external-rest-identity.sh <SANs> -n <namespace>
+#
+# Where <SANs> lists the subject alternative names to put into the generated self-signed 
+# certificate for the external WebLogic Operator REST https interface, for example:
+#
 #   DNS:myhost,DNS:localhost,IP:127.0.0.1 -n weblogic-operator
 #
-# The script creates the secret secret in the weblogic-operator namespace with 
-# the self-signed certificate and private key
+# You should include the addresses of all masters and load balancers in this list.  The certificate
+# cannot be conveniently changed after installation of the operator.
+#
+# The script creates the secret in the weblogic-operator namespace with the self-signed 
+# certificate and private key
 #
 # Example usage:
 #   generate-external-rest-identity.sh IP:127.0.0.1 -n weblogic-operator > my_values.yaml
@@ -78,6 +82,8 @@ set -e
 
 trap "cleanup" EXIT
 
+SECRET_NAME="weblogic-operator-external-rest-identity"
+
 while [ $# -gt 0 ]
   do 
     key="$1"
@@ -124,11 +130,6 @@ then
   usage
 fi
 
-if [ -z "$SECRET_NAME" ]
-then
-  SECRET_NAME="weblogic-operator-external-rest-identity"
-fi
-
 DAYS_VALID="3650"
 TEMP_PW="temp_password"
 OP_PREFIX="weblogic-operator"

site/install.md

@@ -67,21 +67,20 @@ The operator can expose an external REST HTTPS interface which can be accessed f
 To enable the external REST interface, configure these values in a custom configuration file, or on the Helm command line:
 
 * Set `externalRestEnabled` to `true`.
-* Set `externalOperatorCert` to the certificate's Base64 encoded PEM.
-* Set `externalOperatorKey` to the keys Base64 encoded PEM.
+* Set `externalRestIdentitySecret` to the name of the Kubernetes secret that contains the certificate and private key.
 * Optionally, set `externalRestHttpsPort` to the external port number for the operator REST interface (defaults to `31001`).
 
 More detailed information about configuration values can be found in [Operator Helm configuration values](#operator-helm-configuration-values).
 
 ### SSL certificate and private key for the REST interface
 
-For testing purposes, the WebLogic Kubernetes Operator project provides a sample script that generates a self-signed certificate and private key for the operator REST interface and outputs them in YAML format. These values can be added to your custom YAML configuration file, for use when the operator's Helm chart is installed.
+For testing purposes, the WebLogic Kubernetes Operator project provides a sample script that generates a self-signed certificate and private key for the operator REST interface, store them in a Kubernetes tls secret and outputs the corresponding configuration values in YAML format. These values can be added to your custom YAML configuration file, for use when the operator's Helm chart is installed.
 
 ___This script should not be used in a production environment (because self-signed certificates are not typically considered safe).___
 
-The script takes the subject alternative names that should be added to the certificate, for example, the list of hostnames that clients can use to access the external REST interface. In this example, the output is directly appended to your custom YAML configuration:
+The script takes the subject alternative names that should be added to the certificate, for example, the list of hostnames that clients can use to access the external REST interface, the optional secret name to store the certificate (defaults to weblogic-operator-external-rest-identity) and the namespace where the operator will be installed. In this example, the output is directly appended to your custom YAML configuration:
 ```
-$ kubernetes/samples/scripts/rest/generate-external-rest-identity.sh "DNS:${HOSTNAME},DNS:localhost,IP:127.0.0.1" >> custom-values.yaml
+$ kubernetes/samples/scripts/rest/generate-external-rest-identity.sh "DNS:${HOSTNAME},DNS:localhost,IP:127.0.0.1 -n weblogic-operator " >> custom-values.yaml
 ```
 
 ## Optional: Elastic Stack (Elasticsearch, Logstash, and Kibana) integration
@@ -348,7 +347,7 @@ Example:
 externalRestHttpsPort: 32009
 ```
 
-#### externalOperatorCert
+#### externalOperatorCert (Deprecated, use externalRestIdentitySecret instead)
 
 Specifies the user supplied certificate to use for the external operator REST HTTPS interface. The value must be a string containing a Base64 encoded PEM certificate. This parameter is required if `externalRestEnabled` is `true`, otherwise, it is ignored.
 
@@ -367,7 +366,7 @@ Example:
 externalOperatorCert: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUQwakNDQXJxZ0F3S ...
 ```
 
-#### externalOperatorKey
+#### externalOperatorKey (Deprecated, use externalRestIdentitySecret instead)
 
 Specifies user supplied private key to use for the external operator REST HTTPS interface. The value must be a string containing a Base64 encoded PEM key. This parameter is required if `externalRestEnabled` is `true`, otherwise, it is ignored.
 
@@ -385,6 +384,27 @@ Example:
 ```
 externalOperatorKey: QmFnIEF0dHJpYnV0ZXMKICAgIGZyaWVuZGx5TmFtZTogd2VibG9naWMtb3B ...
 ```
+#### externalRestIdentitySecret
+
+Specifies the user supplied secret that contains the tls certificate and private key for the external operator REST HTTPS interface. The value must be the name of the Kubernetes tls secret previously created. This parameter is required if `externalRestEnabled` is `true`, otherwise, it is ignored. In order to create the Kubernetes tls secret you can use the following command:
+`kubectl create secret tls <secret-name> --cert=<path_to_certificate> --key=<path_to_private_key> -n <namespace>`
+
+There is no default value.
+
+The Helm installation will produce an error, similar to the following, if `externalRestIdentitySecret` is not specified (left blank) and `externalRestEnabled` is `true`:
+```
+Error: render error in "weblogic-operator/templates/main.yaml": template: weblogic-operator/templates/main.yaml:9:3: executing "weblogic-operator/templates/main.yaml"
+    at <include "operator.va...>: error calling include: template: weblogic-operator/templates/_validate-inputs.tpl:42:14: executing "operator.validateInputs"
+    at <include "utils.endVa...>: error calling include: template: weblogic-operator/templates/_utils.tpl:22:6: executing "utils.endValidation" 
+    at <fail $scope.validati...>: error calling fail:
+ string externalRestIdentitySecret must be specified
+
+```
+
+Example: externalRestIdentitySecret: weblogic-operator-external-rest-identity
+```
+externalOperatorCert: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUQwakNDQXJxZ0F3S ...
+```
 
 ### Debugging options