From 7b8d4ebb987e4cb8ba195c5b1cb33d732be116f2 Mon Sep 17 00:00:00 2001 From: Mark Nelson Date: Wed, 16 Jan 2019 12:35:08 -0500 Subject: [PATCH 1/2] update rest doc --- site/rest.md | 42 ++++++++++++++++++++++++++++++++++++------ 1 file changed, 36 insertions(+), 6 deletions(-) diff --git a/site/rest.md b/site/rest.md index d2503f761e4..492936a692d 100644 --- a/site/rest.md +++ b/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: ``` From fdb544da22aba7dbb5d5a3239d7142ac56a53708 Mon Sep 17 00:00:00 2001 From: Ryan Eberhard Date: Wed, 16 Jan 2019 16:53:14 -0500 Subject: [PATCH 2/2] Update rest.md --- site/rest.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/site/rest.md b/site/rest.md index 492936a692d..40c81f41d7f 100644 --- a/site/rest.md +++ b/site/rest.md @@ -24,7 +24,7 @@ Before using the sample script below, you must: 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) + 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`. @@ -85,7 +85,7 @@ 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. +**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: