diff --git a/_topic_map.yml b/_topic_map.yml index e48d4f8776..d7c08136f6 100644 --- a/_topic_map.yml +++ b/_topic_map.yml @@ -331,6 +331,8 @@ Topics: Topics: - Name: Ingress Operator in OpenShift Container Platform File: configuring-ingress-operator + - Name: Configuring the default certificate + File: configuring-default-certificate - Name: Ingress controller configuration File: ingress-controller-configuration - Name: Routing from edge load balancers diff --git a/modules/ingress-setting-a-custom-default-certificate.adoc b/modules/ingress-setting-a-custom-default-certificate.adoc deleted file mode 100644 index 2f6827b048..0000000000 --- a/modules/ingress-setting-a-custom-default-certificate.adoc +++ /dev/null @@ -1,72 +0,0 @@ -// Module included in the following assemblies: -// -// * ingress/ingress-operator.adoc - -[id='ingress-setting-a-custom-default-certificate-{context}'] -= Setting a Custom Default Certificate - -You can configure an ingress controller to use a custom certificate by creating a `Secret` resource and editing the `IngressController` custom resource (CR). - -.Prerequisites - -* You must have a certificate/key pair in PEM-encoded files, where the certificate is signed by a trusted certificate authority and valid for the ingress domain. - -* You must have an `IngressController` CR. You may use the default one: -+ ----- -$ oc -n openshift-ingress-operator get ingresscontrollers -NAME AGE -default 10m ----- - -.Procedure - -The following assumes that the custom certificate/key pair are in the `tls.crt` and `tls.key` files in the current working directory. Substitute the actual path names for `tls.crt` and `tls.key`. You also may substitute another name for the `custom-certs-default` when creating the `Secret` resource and referencing it in the `IngressController` CR. - -First, create a `Secret` resource containing the custom certificate in the `openshift-ingress` namespace: - -. Create a `Secret` resource using the `tls.crt` and `tls.key` files. -+ ----- -$ oc -n openshift-ingress create secret tls custom-certs-default --cert=tls.crt --key=tls.key ----- - -Then modify the `IngressController` CR: - -. Open the `IngressController` CR for editing. -+ ----- -$ oc -n openshift-ingress-operator edit ingresscontrollers/default ----- -+ -For example: -+ ----- -oc -n openshift-ingress-operator edit ingresscontrollers/default - -apiVersion: ingresscontroller.operator.openshift.io/v1 -kind: IngressController -metadata: - creationTimestamp: 2019-03-04T00:18:48Z - generation: 1 - name: default - namespace: openshift-ingress-operator - resourceVersion: "15872" - selfLink: /apis/operator.operator.openshift.io/v1/namespaces/openshift-ingress-operator/ingresscontrollers/default - uid: e8f5dc3c-5300-43d5-a0c7-48ebf228634f -namespace: openshift-ingress-operator ----- - -. Change the `defaultCertificate` parameter: -+ -.Sample Ingress Controller -[source,yaml] ----- -spec: - defaultCertificate: - name: "custom-certs-default" <1> ----- - -<1> Name of the `Secret` resource in the `openshift-ingress` namespace with the TLS secret for the ingress controller. - -As soon as the `IngressController` CR has been modified, the ingress operator will update the ingress controller's deployment to use the custom certificate. Note that this action will cause the ingress controller to be redeployed, using a rolling deployment strategy. diff --git a/modules/installation-ingress-config-asset.adoc b/modules/installation-ingress-config-asset.adoc deleted file mode 100644 index 6cdb354b24..0000000000 --- a/modules/installation-ingress-config-asset.adoc +++ /dev/null @@ -1,26 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_aws/installing-aws-customizations.adoc - - -[id='installation-ingress-config-asset-{context}'] -= The `Ingress` Configuration Asset - -The installer generates an asset with an `Ingress` resource in the `config.openshift.io` API group: - -.YAML Definition of the `Ingress` resource (`cluster-ingress-02-config.yml`): -[source,yaml] ----- -apiVersion: config.openshift.io/v1 -kind: Ingress -metadata: - name: cluster -spec: - domain: apps.openshiftdemos.com ----- - -The installer stores this asset in the `cluster-ingress-02-config.yml` file in the `manifests/` directory. This `Ingress` resource defines the cluster-wide configuration for ingress. This ingress configuration is used as follows: - -* The ingress operator uses the domain from the cluster ingress configuration as the domain for the default ingress controller. - -* The OpenShift API server operator uses the domain from the cluster ingress configuration as the domain used when generating a default host for a `Route` resource that does not specify an explicit host. diff --git a/modules/ingress-creating-a-reencrypt-route-with-a-custom-certificate.adoc b/modules/nw-ingress-creating-a-reencrypt-route-with-a-custom-certificate.adoc similarity index 56% rename from modules/ingress-creating-a-reencrypt-route-with-a-custom-certificate.adoc rename to modules/nw-ingress-creating-a-reencrypt-route-with-a-custom-certificate.adoc index e3a2d15646..fa11835e1c 100644 --- a/modules/ingress-creating-a-reencrypt-route-with-a-custom-certificate.adoc +++ b/modules/nw-ingress-creating-a-reencrypt-route-with-a-custom-certificate.adoc @@ -2,16 +2,19 @@ // // * ingress/routes.adoc -[id='olm-why-use-operators-{context}'] -= How Do I Create a Reencrypt Route with a Custom Certificate? +[id='nw-ingress-creating-a-reencrypt-route-with-a-custom-certificate-{context}'] += Creating a re-encrypt route with a custom certificate -You can configure a secure route using reencrypt TLS termination with a custom certificate by using the `oc create route` command. +You can configure a secure route using reencrypt TLS termination with a custom +certificate by using the `oc create route` command. .Prerequisites -* You must have a certificate/key pair in PEM-encoded files, where the certificate is valid for the route host. +* You must have a certificate/key pair in PEM-encoded files, where the certificate +is valid for the route host. -* You may have a separate CA certificate in a PEM-encoded file that completes the certificate chain. +* You may have a separate CA certificate in a PEM-encoded file that completes +the certificate chain. * You must have a separate destination CA certificate in a PEM-encoded file. @@ -19,7 +22,8 @@ You can configure a secure route using reencrypt TLS termination with a custom c [NOTE] ==== -Password protected key files are not supported. To remove a passphrase from a key file, use the following command: +Password protected key files are not supported. To remove a passphrase from a +key file, use the following command: ---- $ openssl rsa -in password_protected_tls.key -out tls.key ---- @@ -27,17 +31,26 @@ $ openssl rsa -in password_protected_tls.key -out tls.key .Procedure -This procedure creates a `Route` resource with a custom certificate and reencrypt TLS termination. The following assumes that the certificate/key pair are in the `tls.crt` and `tls.key` files in the current working directory. You must also specify a destination CA certificate to enable the ingress controller to trust the service's certificate. You may also specify a CA certificate if needed to complete the certificate chain. Substitute the actual path names for `tls.crt`, `tls.key`, `cacert.crt`, and (optionally) `ca.crt`. Substitute the name of the `Service` resource that you want to expose for `frontend`. Substitute the appropriate host name for `www.example.com`. +This procedure creates a `Route` resource with a custom certificate and +reencrypt TLS termination. The following assumes that the certificate/key pair +are in the `tls.crt` and `tls.key` files in the current working directory. You +must also specify a destination CA certificate to enable the ingress controller +to trust the service's certificate. You may also specify a CA certificate if +needed to complete the certificate chain. Substitute the actual path names for +`tls.crt`, `tls.key`, `cacert.crt`, and (optionally) `ca.crt`. Substitute the +name of the `Service` resource that you want to expose for `frontend`. +Substitute the appropriate host name for `www.example.com`. -. Create a secure `Route` resource using reencrypt TLS termination and a custom certificate. +* Create a secure `Route` resource using reencrypt TLS termination and a custom +certificate: + ---- $ oc create route reencrypt --service=frontend --cert=tls.crt --key=tls.key --dest-ca-cert=destca.crt --ca-cert=ca.crt --hostname=www.example.com ---- - -If you examine the resulting `Route` resource, it should look similar to the following: - - ++ +If you examine the resulting `Route` resource, it should look similar to the +following: ++ .YAML Definition of the Secure Route [source,yaml] ---- @@ -69,5 +82,5 @@ spec: [...] -----END CERTIFICATE----- ---- - ++ See `oc create route reencrypt --help` for more options. diff --git a/modules/ingress-creating-an-edge-route-with-a-custom-certificate.adoc b/modules/nw-ingress-creating-an-edge-route-with-a-custom-certificate.adoc similarity index 57% rename from modules/ingress-creating-an-edge-route-with-a-custom-certificate.adoc rename to modules/nw-ingress-creating-an-edge-route-with-a-custom-certificate.adoc index ddd9155f69..5ab9aaea08 100644 --- a/modules/ingress-creating-an-edge-route-with-a-custom-certificate.adoc +++ b/modules/nw-ingress-creating-an-edge-route-with-a-custom-certificate.adoc @@ -2,22 +2,26 @@ // // * ingress/routes.adoc -[id='olm-why-use-operators-{context}'] -= How Do I Create an Edge Route with a Custom Certificate? +[id='nw-ingress-creating-an-edge-route-with-a-custom-certificate-{context}'] += Creating an edge route with a custom certificate -You can configure a secure route using edge TLS termination with a custom certificate by using the `oc create route` command. +You can configure a secure route using edge TLS termination with a custom +certificate by using the `oc create route` command. .Prerequisites -* You must have a certificate/key pair in PEM-encoded files, where the certificate is valid for the route host. +* You must have a certificate/key pair in PEM-encoded files, where the certificate +is valid for the route host. -* You may have a separate CA certificate in a PEM-encoded file that completes the certificate chain. +* You may have a separate CA certificate in a PEM-encoded file that completes +the certificate chain. * You must have a `Service` resource that you want to expose. [NOTE] ==== -Password protected key files are not supported. To remove a passphrase from a key file, use the following command: +Password protected key files are not supported. To remove a passphrase from a +key file, use the following command: ---- $ openssl rsa -in password_protected_tls.key -out tls.key ---- @@ -25,17 +29,23 @@ $ openssl rsa -in password_protected_tls.key -out tls.key .Procedure -This procedure creates a `Route` resource with a custom certificate and edge TLS termination. The following assumes that the certificate/key pair are in the `tls.crt` and `tls.key` files in the current working directory. You may also specify a CA certificate if needed to complete the certificate chain. Substitute the actual path names for `tls.crt`, `tls.key`, and (optionally) `ca.crt`. Substitute the name of the `Service` resource that you want to expose for `frontend`. Substitute the appropriate host name for `www.example.com`. +This procedure creates a `Route` resource with a custom certificate and edge TLS +termination. The following assumes that the certificate/key pair are in the +`tls.crt` and `tls.key` files in the current working directory. You may also +specify a CA certificate if needed to complete the certificate chain. +Substitute the actual path names for `tls.crt`, `tls.key`, and (optionally) +`ca.crt`. Substitute the name of the `Service` resource that you want to expose +for `frontend`. Substitute the appropriate host name for `www.example.com`. -. Create a secure `Route` resource using edge TLS termination and a custom certificate. +* Create a secure `Route` resource using edge TLS termination and a custom certificate. + ---- $ oc create route edge --service=frontend --cert=tls.crt --key=tls.key --ca-cert=ca.crt --hostname=www.example.com ---- - -If you examine the resulting `Route` resource, it should look similar to the following: - - ++ +If you examine the resulting `Route` resource, it should look similar to the +following: ++ .YAML Definition of the Secure Route [source,yaml] ---- @@ -63,5 +73,5 @@ spec: [...] -----END CERTIFICATE----- ---- - ++ See `oc create route edge --help` for more options. diff --git a/modules/nw-ingress-setting-a-custom-default-certificate.adoc b/modules/nw-ingress-setting-a-custom-default-certificate.adoc new file mode 100644 index 0000000000..1cc3eedceb --- /dev/null +++ b/modules/nw-ingress-setting-a-custom-default-certificate.adoc @@ -0,0 +1,85 @@ +// Module included in the following assemblies: +// +// * ingress/ingress-operator.adoc + +[id='nw-ingress-setting-a-custom-default-certificate-{context}'] += Setting a custom default certificate + +As an administrator, you can configure an ingress controller to use a custom +certificate by creating a `Secret` resource and editing the `IngressController` +custom resource (CR). + +.Prerequisites + +* You must have a certificate/key pair in PEM-encoded files, where the +certificate is signed by a trusted certificate authority and valid for the +ingress domain. + +* You must have an `IngressController` CR. You may use the default one: ++ +---- +$ oc -n openshift-ingress-operator get ingresscontrollers +NAME AGE +default 10m +---- + +.Procedure + +The following assumes that the custom certificate and key pair are in the +`tls.crt` and `tls.key` files in the current working directory. Substitute the +actual path names for `tls.crt` and `tls.key`. You also may substitute another +name for `custom-certs-default` when creating the `Secret` resource and +referencing it in the `IngressController` CR. + +. Create a `Secret` resource containing the custom certificate in the +`openshift-ingress` namespace. ++ +.. Create a `Secret` resource using the `tls.crt` and `tls.key` files. ++ +---- +$ oc -n openshift-ingress create secret tls custom-certs-default --cert=tls.crt --key=tls.key +---- ++ +. Modify the `IngressController` CR: ++ +.. Open the `IngressController` CR for editing: ++ +---- +$ oc -n openshift-ingress-operator edit ingresscontrollers/default +---- ++ +For example: ++ +---- +oc -n openshift-ingress-operator edit ingresscontrollers/default + +apiVersion: ingresscontroller.operator.openshift.io/v1 +kind: IngressController +metadata: + creationTimestamp: 2019-03-04T00:18:48Z + generation: 1 + name: default + namespace: openshift-ingress-operator + resourceVersion: "15872" + selfLink: /apis/operator.operator.openshift.io/v1/namespaces/openshift-ingress-operator/ingresscontrollers/default + uid: e8f5dc3c-5300-43d5-a0c7-48ebf228634f +namespace: openshift-ingress-operator +---- ++ +.. Change the `defaultCertificate` parameter: ++ +.Sample Ingress Controller +[source,yaml] +---- +spec: + defaultCertificate: + name: "custom-certs-default" <1> +---- ++ +<1> Name of the `Secret` resource in the `openshift-ingress` namespace with the +TLS secret for the ingress controller. ++ +As soon as the `IngressController` CR has been modified, the ingress operator +will update the ingress controller's deployment to use the custom certificate. +Note that this action will cause the ingress controller to be redeployed, using +a rolling deployment strategy. diff --git a/modules/nw-installation-ingress-config-asset.adoc b/modules/nw-installation-ingress-config-asset.adoc new file mode 100644 index 0000000000..4480d65aa7 --- /dev/null +++ b/modules/nw-installation-ingress-config-asset.adoc @@ -0,0 +1,33 @@ +// Module included in the following assemblies: +// +// * installing/installing_aws/installing-aws-customizations.adoc +// * networking/ingress/configuring_ingress_operator.adoc + + +[id='nw-installation-ingress-config-asset-{context}'] += The Ingress Operator configuration asset + +The installer generates an asset with an `Ingress` resource in the +`config.openshift.io` API group, `cluster-ingress-02-config.yml`. + +.YAML Definition of the `Ingress` resource +[source,yaml] +---- +apiVersion: config.openshift.io/v1 +kind: Ingress +metadata: + name: cluster +spec: + domain: apps.openshiftdemos.com +---- + +The installer stores this asset in the `cluster-ingress-02-config.yml` file in +the `manifests/` directory. This `Ingress` resource defines the cluster-wide +configuration for ingress. This ingress configuration is used as follows: + +* The ingress operator uses the domain from the cluster ingress configuration as +the domain for the default ingress controller. + +* The OpenShift API server operator uses the domain from the cluster ingress +configuration as the domain used when generating a default host for a `Route` +resource that does not specify an explicit host. diff --git a/networking/ingress/configuring-default-certificate.adoc b/networking/ingress/configuring-default-certificate.adoc new file mode 100644 index 0000000000..8ead47e8ea --- /dev/null +++ b/networking/ingress/configuring-default-certificate.adoc @@ -0,0 +1,16 @@ +[id="configuring-default-certificate"] += Configuring the default certificate +include::modules/common-attributes.adoc[] +:context: configuring-default-certificate + +toc::[] + +The following sections describe how to set a custom default certificate for +administrators, and how to create a re-encrypt route with a custom certificate +and create an edge route with a custom certificate for developers. + +include::modules/nw-ingress-setting-a-custom-default-certificate.adoc[leveloffset=+1] + +include::modules/nw-ingress-creating-a-reencrypt-route-with-a-custom-certificate.adoc[leveloffset=+1] + +include::modules/nw-ingress-creating-an-edge-route-with-a-custom-certificate.adoc[leveloffset=+1] diff --git a/networking/ingress/configuring-ingress-operator.adoc b/networking/ingress/configuring-ingress-operator.adoc index d953322b3c..4b2f5fa941 100644 --- a/networking/ingress/configuring-ingress-operator.adoc +++ b/networking/ingress/configuring-ingress-operator.adoc @@ -15,6 +15,8 @@ HAProxy-based Kubernetes Ingress controller. Ingress Operator implements the OpenShift `ingresscontroller` API. +include::modules/nw-installation-ingress-config-asset.adoc[leveloffset=+1] + include::modules/nw-ingress-view.adoc[leveloffset=+1] include::modules/nw-ingress-operator-status.adoc[leveloffset=+1]