Merge pull request #9549 from heww/update-configure-https

docs(https): update configure_https.md
This commit is contained in:
Daniel Jiang 2019-10-23 16:59:42 +08:00 committed by GitHub
commit a612cefc94
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23

View File

@ -2,7 +2,7 @@
Because Harbor does not ship with any certificates, it uses HTTP by default to serve registry requests. However, it is highly recommended that security be enabled for any production environment. Harbor has an Nginx instance as a reverse proxy for all services, you can use the prepare script to configure Nginx to enable https. Because Harbor does not ship with any certificates, it uses HTTP by default to serve registry requests. However, it is highly recommended that security be enabled for any production environment. Harbor has an Nginx instance as a reverse proxy for all services, you can use the prepare script to configure Nginx to enable https.
In a test or development environment, you may choose to use a self-signed certificate instead of the one from a trusted third-party CA. The followings will show you how to create your own CA, and use your CA to sign a server certificate and a client certificate. In a test or development environment, you may choose to use a self-signed certificate instead of the one from a trusted third-party CA. The followings will show you how to create your own CA, and use your CA to sign a server certificate and a client certificate.
## Getting Certificate Authority ## Getting Certificate Authority
@ -11,7 +11,7 @@ In a test or development environment, you may choose to use a self-signed certif
``` ```
``` ```
openssl req -x509 -new -nodes -sha512 -days 3650 \ openssl req -x509 -new -nodes -sha512 -days 3650 \
-subj "/C=TW/ST=Taipei/L=Taipei/O=example/OU=Personal/CN=yourdomain.com" \ -subj "/C=CN/ST=Beijing/L=Beijing/O=example/OU=Personal/CN=yourdomain.com" \
-key ca.key \ -key ca.key \
-out ca.crt -out ca.crt
``` ```
@ -34,9 +34,9 @@ If you use FQDN like **yourdomain.com** to connect your registry host, then you
``` ```
openssl req -sha512 -new \ openssl req -sha512 -new \
-subj "/C=TW/ST=Taipei/L=Taipei/O=example/OU=Personal/CN=yourdomain.com" \ -subj "/C=CN/ST=Beijing/L=Beijing/O=example/OU=Personal/CN=yourdomain.com" \
-key yourdomain.com.key \ -key yourdomain.com.key \
-out yourdomain.com.csr -out yourdomain.com.csr
``` ```
**3) Generate the certificate of your registry host:** **3) Generate the certificate of your registry host:**
@ -50,7 +50,7 @@ cat > v3.ext <<-EOF
authorityKeyIdentifier=keyid,issuer authorityKeyIdentifier=keyid,issuer
basicConstraints=CA:FALSE basicConstraints=CA:FALSE
keyUsage = digitalSignature, nonRepudiation, keyEncipherment, dataEncipherment keyUsage = digitalSignature, nonRepudiation, keyEncipherment, dataEncipherment
extendedKeyUsage = serverAuth extendedKeyUsage = serverAuth
subjectAltName = @alt_names subjectAltName = @alt_names
[alt_names] [alt_names]
@ -73,17 +73,17 @@ EOF
**1) Configure Server Certificate and Key for Harbor** **1) Configure Server Certificate and Key for Harbor**
After obtaining the **yourdomain.com.crt** and **yourdomain.com.key** files, After obtaining the **yourdomain.com.crt** and **yourdomain.com.key** files,
you can put them into directory such as ```/root/cert/```: you can put them into directory such as ```/root/cert/```:
``` ```
cp yourdomain.com.crt /data/cert/ cp yourdomain.com.crt /data/cert/
cp yourdomain.com.key /data/cert/ cp yourdomain.com.key /data/cert/
``` ```
**2) Configure Server Certificate, Key and CA for Docker** **2) Configure Server Certificate, Key and CA for Docker**
The Docker daemon interprets ```.crt``` files as CA certificates and ```.cert``` files as client certificates. The Docker daemon interprets ```.crt``` files as CA certificates and ```.cert``` files as client certificates.
Convert server ```yourdomain.com.crt``` to ```yourdomain.com.cert```: Convert server ```yourdomain.com.crt``` to ```yourdomain.com.cert```:
@ -103,7 +103,7 @@ The following illustrates a configuration with custom certificates:
``` ```
/etc/docker/certs.d/ /etc/docker/certs.d/
└── yourdomain.com:port └── yourdomain.com:port
├── yourdomain.com.cert <-- Server certificate signed by CA ├── yourdomain.com.cert <-- Server certificate signed by CA
├── yourdomain.com.key <-- Server key signed by CA ├── yourdomain.com.key <-- Server key signed by CA
└── ca.crt <-- Certificate authority that signed the registry certificate └── ca.crt <-- Certificate authority that signed the registry certificate
@ -151,11 +151,11 @@ Finally, restart Harbor:
``` ```
After setting up HTTPS for Harbor, you can verify it by the following steps: After setting up HTTPS for Harbor, you can verify it by the following steps:
* Open a browser and enter the address: https://yourdomain.com. It should display the user interface of Harbor. * Open a browser and enter the address: https://yourdomain.com. It should display the user interface of Harbor.
* Notice that some browser may still shows the warning regarding Certificate Authority (CA) unknown for security reason even though we signed certificates by self-signed CA and deploy the CA to the place mentioned above. It is because self-signed CA essentially is not a trusted third-party CA. You can import the CA to the browser on your own to solve the warning. * Notice that some browser may still shows the warning regarding Certificate Authority (CA) unknown for security reason even though we signed certificates by self-signed CA and deploy the CA to the place mentioned above. It is because self-signed CA essentially is not a trusted third-party CA. You can import the CA to the browser on your own to solve the warning.
* On a machine with Docker daemon, make sure the option "-insecure-registry" for https://yourdomain.com is not present. * On a machine with Docker daemon, make sure the option "-insecure-registry" for https://yourdomain.com is not present.
* If you mapped nginx port 443 to another port, then you should instead create the directory ```/etc/docker/certs.d/yourdomain.com:port``` (or your registry host IP:port). Then run any docker command to verify the setup, e.g. * If you mapped nginx port 443 to another port, then you should instead create the directory ```/etc/docker/certs.d/yourdomain.com:port``` (or your registry host IP:port). Then run any docker command to verify the setup, e.g.
@ -171,21 +171,21 @@ If you've mapped nginx 443 port to another, you need to add the port to login, l
## Troubleshooting ## Troubleshooting
1. You may get an intermediate certificate from a certificate issuer. In this case, you should merge the intermediate certificate with your own certificate to create a certificate bundle. You can achieve this by the below command: 1. You may get an intermediate certificate from a certificate issuer. In this case, you should merge the intermediate certificate with your own certificate to create a certificate bundle. You can achieve this by the below command:
``` ```
cat intermediate-certificate.pem >> yourdomain.com.crt cat intermediate-certificate.pem >> yourdomain.com.crt
``` ```
2. On some systems where docker daemon runs, you may need to trust the certificate at OS level. 2. On some systems where docker daemon runs, you may need to trust the certificate at OS level.
On Ubuntu, this can be done by below commands: On Ubuntu, this can be done by below commands:
```sh ```sh
cp yourdomain.com.crt /usr/local/share/ca-certificates/yourdomain.com.crt cp yourdomain.com.crt /usr/local/share/ca-certificates/yourdomain.com.crt
update-ca-certificates update-ca-certificates
``` ```
On Red Hat (CentOS etc), the commands are: On Red Hat (CentOS etc), the commands are:
```sh ```sh
cp yourdomain.com.crt /etc/pki/ca-trust/source/anchors/yourdomain.com.crt cp yourdomain.com.crt /etc/pki/ca-trust/source/anchors/yourdomain.com.crt
update-ca-trust update-ca-trust