Merge pull request #801 from oracle/rest-doc-update

update rest doc

Author: rjeberhard

site/rest.md

@@ -18,13 +18,41 @@ curl ... -H X-RequestedBy:MyClient ... -X POST .../scaling
 If you do not pass in the X-Requested-By header, then you'll get a 400 (bad request) response without any details explaining why the request is bad.
 The X-Requested-By header is not needed for requests that only read, for example when you GET any of the Operator's REST endpoints.
 
-If using `curl`, you can use the `-k` option to bypass the check to verify that the operator's certificate is trusted (instead of `curl --cacert`).
+Before using the sample script below, you must:
 
-Here is a small sample BASH script that may help to prepare the necessary token, certificates, and such, to call the operator's REST services:
+* Update it to ensure it has the correct service account, namespaces, etc., and it points to the `values.yaml`
+  that you used to install the operator (so that it can get the certificates),
+* Add your operator's certificate to your operating system's trust store (see below), and
+* If you are using a self-signed certificate and your client is macOS, you may need to update the version of `curl`
+  you have installed.  The version of CURL that ships with macOS High Sierra (`curl 7.54.0 (x86_64-apple-darwin17.0)
+  libcurl/7.54.0 LibreSSL/2.0.20 zlib/1.2.11 nghttp2/1.24.0`) has known issues with self-signed certificates.  Oracle
+  recommends `curl 7.63.0 (x86_64-apple-darwin17.7.0) libcurl/7.63.0 SecureTransport zlib/1.2.11` which can be installed
+  with `brew install curl`.
 
-Before using this script it would be necessary to update it to ensure it has the correct 
-service account, namespaces, etc., and it points to your `values.yaml` that you used to install
-the operator (so that it can get the certificates). 
+### How to add your certificate to your operating system trust store
+
+For macOS, find the certificate in Finder, and double-click on it.  This will add it to your keystore and open Keychain
+Access.  Find the certificate in Keychain Access and double-click on it to open the details.  Open the "Trust" pull-down
+and set the value of "When using this certificate" to "Always Trust", then close the detail window and enter your
+password when prompted.
+
+For Oracle Linux, run the script below once to copy the certificate into `/tmp/operator.cert.pem` then run these
+commands to add the certificate to the trust store:
+
+```
+$ sudo cp /tmp/operator.cert.pem /etc/pki/ca-trust/source/anchors/
+$ sudo update-ca-trust enable; sudo update-ca-trust extract
+$ openssl x509 -noout -hash -in /tmp/operator.cert.pem
+$ sudo ln -s /etc/pki/ca-trust/source/anchors/operator.cert.pem /etc/pki/tls/certs/e242d2da.0
+```
+In the final command, the filename `e242d2da.0` should be the output of the previous command plus the suffix `.0`.
+
+Please consult your operating system's documentation (or Google) for other operating systems.
+
+### Sample operator REST client script
+
+Here is a small sample BASH script that may help to prepare the necessary token, certificates, and such, to call the
+operator's REST services.  Please read the important caveats above before using this script:
 
 ```
 #!/bin/bash
@@ -44,7 +72,7 @@ cat ${OPERATOR_CERT_FILE}
 echo "Ready to call operator REST APIs"
 
 STATUS_CODE=`curl \
-  -v -k \
+  -v \
   --cacert ${OPERATOR_CERT_FILE} \
   -H "Authorization: Bearer ${TOKEN}" \
   -H Accept:application/json \
@@ -57,6 +85,8 @@ cat curl.err
 cat curl.out | jq .
 ```
 
+**Note**: you can use the `-k` option to bypass the check to verify that the operator's certificate is trusted (instead of `curl --cacert`), but this is insecure.
+
 To use this script, pass in the Kubernetes server address and then the URL you want to call.   The script assumes `jq` is installed and uses it to format the response.  This can be removed if desired.  The script also prints out quite a bit of useful debugging information in addition to the response.  Here is an example of the output of this script:
 
 ```