From b5faa28568ac2128c675963c4f45cf98f94df010 Mon Sep 17 00:00:00 2001 From: Weii Wang Date: Mon, 29 Jun 2026 12:32:50 +0800 Subject: [PATCH 1/5] Add documentation on using self-signed certificates --- docs/how-to/use-self-signed-certificates.md | 117 ++++++++++++++++++++ 1 file changed, 117 insertions(+) create mode 100644 docs/how-to/use-self-signed-certificates.md diff --git a/docs/how-to/use-self-signed-certificates.md b/docs/how-to/use-self-signed-certificates.md new file mode 100644 index 000000000..b81442442 --- /dev/null +++ b/docs/how-to/use-self-signed-certificates.md @@ -0,0 +1,117 @@ +# How to use self-signed certificates + +If you wish HAProxy to serve HTTPS content using a self-signed certificate, +there are two major ways to do this. + +## Use `self-signed-certificates` charm + +If your use case only requires a general self-signed certificate, instead of a +specific self-signed certificate, you can use the +[`self-signed-certificates` charm](https://charmhub.io/self-signed-certificates). + +The self-signed-certificates charm will generate a self-signed CA inside the +charm and then use it to sign certificates for the HAProxy charm. This is the +simplest way to set up self-signed certificates for the HAProxy charm. + +To use the self-signed-certificates charm with the HAProxy charm, simply deploy +the self-signed-certificates charm and integrate it with the HAProxy charm using +the `certificates` relation. + +``` +juju deploy haproxy --channel=2.8/stable +juju deploy pollen --channel=latest/edge +juju integrate haproxy:haproxy-route pollen + +juju deploy self-signed-certificates +juju integrate self-signed-certificates haproxy:certificates +``` + +And then verify HAProxy is using the self-signed certificates signed by the +self-signed-certificates charm. + +``` +juju config haproxy external-hostname=pollen.test +HAPROXY_IP=$(juju status --format json | jq -r '.applications.haproxy.units."haproxy/0"."public-address"') +curl -k -v --resolve "pollen.test:443:$HAPROXY_IP" https://pollen.test +``` + +In the output, you should see the HAProxy charm is using the certificates signed +by the self-signed-certificates charm. + +``` +... +* issuer: CN=self-signed-certificates-operator; x500UniqueIdentifier=e964420b-6ae9-4955-87f8-0a797ef5fd24 +... +``` + +## Use `manual-tls-certificates` charm + +If you wish to sign the certificates used by the HAProxy charm using a custom CA +you own, you can use the [`manual-tls-certificates`](https://charmhub.io/manual-tls-certificates) charm. + +HAProxy charm will generate a CSR (certificate signing request), which will be +transmitted to the manual-tls-certificates charm. And then you can sign the +CSR using your own CA using the `get-outstanding-certificate-requests` and +`provide-certificate` actions of the manual-tls-certificates charm. + +Similar to the `self-signed-certificates` charm, to use the +manual-tls-certificates charm with the HAProxy charm, deploy the +manual-tls-certificates charm and integrate it with the HAProxy charm using +the `certificates` relation. + +``` +juju deploy haproxy --channel=2.8/stable +juju deploy pollen --channel=latest/edge +juju integrate haproxy:haproxy-route pollen + +juju deploy manual-tls-certificates +juju integrate manual-tls-certificates haproxy:certificates +``` + +Let's then create a test CA for signing certificates for the HAProxy charm. + +``` +mkdir certs +openssl genrsa -out certs/ca.key 2048 +openssl req -new -x509 -days 3650 -key certs/ca.key -out certs/ca.crt -subj "/C=US/CN=ca.test" +``` + +Now sign the CSR of the HAProxy charm by first retrieving the CSR from the +manual-tls-certificates charm. + +``` +juju config haproxy external-hostname=pollen.test +juju run manual-tls-certificates/leader get-outstanding-certificate-requests --format=json \ + | jq -r '."manual-tls-certificates/0".results.result' \ + | jq -r '.[0].csr' > certs/client.csr +``` + +Then sign the CSR using the CA we created earlier and provide the signed +certificate back to the `manual-tls-certificates` charm. + +``` +openssl x509 -req -in certs/client.csr -CA certs/ca.crt -CAkey certs/ca.key -CAcreateserial -out certs/client.crt -days 365 -sha256 +juju run manual-tls-certificates/leader provide-certificate \ + certificate="$(base64 -w0 certs/client.crt)" \ + ca-certificate="$(base64 -w0 certs/ca.crt)" \ + certificate-signing-request="$(base64 -w0 certs/client.csr)" +``` + +Verify HAProxy is using the certificates signed by the CA (`ca.test`) we created +earlier. + +``` +HAPROXY_IP=$(juju status --format json | jq -r '.applications.haproxy.units."haproxy/0"."public-address"') +curl -k -vv --resolve "pollen.test:443:$HAPROXY_IP" https://pollen.test +``` + +``` +12:28:19.254023 [0-0] * Server certificate: +12:28:19.254047 [0-0] * subject: CN=pollen.test; x500UniqueIdentifier=cdb08400-f565-46cf-b3a9-86a3c566e4e5 +12:28:19.254066 [0-0] * start date: Jun 29 04:26:41 2026 GMT +12:28:19.254085 [0-0] * expire date: Jun 29 04:26:41 2027 GMT +12:28:19.254103 [0-0] * issuer: C=US; CN=ca.test +12:28:19.254122 [0-0] * Certificate level 0: Public key type RSA (2048/112 Bits/secBits), signed using sha256WithRSAEncryption +12:28:19.254141 [0-0] * Certificate level 1: Public key type RSA (2048/112 Bits/secBits), signed using sha256WithRSAEncryption +12:28:19.254157 [0-0] * SSL certificate verification failed, continuing anyway! +``` From a7efd31ea1637c79947aae01f5bce6f2442f6978 Mon Sep 17 00:00:00 2001 From: Weii Wang Date: Mon, 29 Jun 2026 12:43:36 +0800 Subject: [PATCH 2/5] Add index --- docs/how-to/index.md | 1 + docs/how-to/use-self-signed-certificates.md | 2 ++ 2 files changed, 3 insertions(+) diff --git a/docs/how-to/index.md b/docs/how-to/index.md index 095c4a197..063a5c686 100644 --- a/docs/how-to/index.md +++ b/docs/how-to/index.md @@ -44,6 +44,7 @@ against vulnerabilities and attacks. :maxdepth: 1 Enable DDoS Protection Protect a hostname using OpenID Connect +Use self-signed certificates ``` ## Maintenance and development diff --git a/docs/how-to/use-self-signed-certificates.md b/docs/how-to/use-self-signed-certificates.md index b81442442..65b1872b2 100644 --- a/docs/how-to/use-self-signed-certificates.md +++ b/docs/how-to/use-self-signed-certificates.md @@ -1,3 +1,5 @@ +(how_to_use_self_signed_certificates)= + # How to use self-signed certificates If you wish HAProxy to serve HTTPS content using a self-signed certificate, From 1f883e522b7cdca9c6ef58b919db33287468d023 Mon Sep 17 00:00:00 2001 From: Weii Wang Date: Wed, 8 Jul 2026 00:15:06 +0800 Subject: [PATCH 3/5] Apply suggestions from code review Co-authored-by: Erin Conley --- docs/how-to/use-self-signed-certificates.md | 50 ++++++++------------- 1 file changed, 18 insertions(+), 32 deletions(-) diff --git a/docs/how-to/use-self-signed-certificates.md b/docs/how-to/use-self-signed-certificates.md index 65b1872b2..6f6a4984c 100644 --- a/docs/how-to/use-self-signed-certificates.md +++ b/docs/how-to/use-self-signed-certificates.md @@ -2,18 +2,18 @@ # How to use self-signed certificates -If you wish HAProxy to serve HTTPS content using a self-signed certificate, -there are two major ways to do this. +If you need HAProxy to serve HTTPS content using a self-signed certificate, +there are two major ways depending on whether your use case requires a +general or specific certificate. -## Use `self-signed-certificates` charm +## Use a general self-signed certificate -If your use case only requires a general self-signed certificate, instead of a -specific self-signed certificate, you can use the +If your use case only requires a general self-signed certificate, +you can use the [`self-signed-certificates` charm](https://charmhub.io/self-signed-certificates). The self-signed-certificates charm will generate a self-signed CA inside the -charm and then use it to sign certificates for the HAProxy charm. This is the -simplest way to set up self-signed certificates for the HAProxy charm. +charm and then use it to sign certificates for the HAProxy charm. To use the self-signed-certificates charm with the HAProxy charm, simply deploy the self-signed-certificates charm and integrate it with the HAProxy charm using @@ -28,7 +28,7 @@ juju deploy self-signed-certificates juju integrate self-signed-certificates haproxy:certificates ``` -And then verify HAProxy is using the self-signed certificates signed by the +Verify HAProxy is using the self-signed certificates signed by the self-signed-certificates charm. ``` @@ -40,24 +40,19 @@ curl -k -v --resolve "pollen.test:443:$HAPROXY_IP" https://pollen.test In the output, you should see the HAProxy charm is using the certificates signed by the self-signed-certificates charm. -``` -... -* issuer: CN=self-signed-certificates-operator; x500UniqueIdentifier=e964420b-6ae9-4955-87f8-0a797ef5fd24 -... -``` -## Use `manual-tls-certificates` charm +## Use a custom CA to sign certificates If you wish to sign the certificates used by the HAProxy charm using a custom CA you own, you can use the [`manual-tls-certificates`](https://charmhub.io/manual-tls-certificates) charm. -HAProxy charm will generate a CSR (certificate signing request), which will be -transmitted to the manual-tls-certificates charm. And then you can sign the -CSR using your own CA using the `get-outstanding-certificate-requests` and -`provide-certificate` actions of the manual-tls-certificates charm. +The HAProxy charm will generate a certificate signing request (CSR), which will be +transmitted to the `manual-tls-certificates` charm. Sign the +CSR with your own CA using the `get-outstanding-certificate-requests` and +`provide-certificate` actions of the `manual-tls-certificates` charm. -Similar to the `self-signed-certificates` charm, to use the -manual-tls-certificates charm with the HAProxy charm, deploy the +To use the +`manual-tls-certificates` charm with the HAProxy charm, deploy the manual-tls-certificates charm and integrate it with the HAProxy charm using the `certificates` relation. @@ -88,8 +83,8 @@ juju run manual-tls-certificates/leader get-outstanding-certificate-requests --f | jq -r '.[0].csr' > certs/client.csr ``` -Then sign the CSR using the CA we created earlier and provide the signed -certificate back to the `manual-tls-certificates` charm. +Then sign the CSR using the CA we created earlier, and provide the signed +certificate back to the `manual-tls-certificates` charm using the `provide-certificate` action. ``` openssl x509 -req -in certs/client.csr -CA certs/ca.crt -CAkey certs/ca.key -CAcreateserial -out certs/client.crt -days 365 -sha256 @@ -106,14 +101,5 @@ earlier. HAPROXY_IP=$(juju status --format json | jq -r '.applications.haproxy.units."haproxy/0"."public-address"') curl -k -vv --resolve "pollen.test:443:$HAPROXY_IP" https://pollen.test ``` +In the output, you should see the HAProxy charm is using the custom CA: -``` -12:28:19.254023 [0-0] * Server certificate: -12:28:19.254047 [0-0] * subject: CN=pollen.test; x500UniqueIdentifier=cdb08400-f565-46cf-b3a9-86a3c566e4e5 -12:28:19.254066 [0-0] * start date: Jun 29 04:26:41 2026 GMT -12:28:19.254085 [0-0] * expire date: Jun 29 04:26:41 2027 GMT -12:28:19.254103 [0-0] * issuer: C=US; CN=ca.test -12:28:19.254122 [0-0] * Certificate level 0: Public key type RSA (2048/112 Bits/secBits), signed using sha256WithRSAEncryption -12:28:19.254141 [0-0] * Certificate level 1: Public key type RSA (2048/112 Bits/secBits), signed using sha256WithRSAEncryption -12:28:19.254157 [0-0] * SSL certificate verification failed, continuing anyway! -``` From 7030303fdb422c186ffdd9cf098e58db554536cc Mon Sep 17 00:00:00 2001 From: Weii Wang Date: Wed, 8 Jul 2026 18:29:05 +0800 Subject: [PATCH 4/5] Fix linting issues --- docs/how-to/use-self-signed-certificates.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/how-to/use-self-signed-certificates.md b/docs/how-to/use-self-signed-certificates.md index 6f6a4984c..d33272b28 100644 --- a/docs/how-to/use-self-signed-certificates.md +++ b/docs/how-to/use-self-signed-certificates.md @@ -40,7 +40,6 @@ curl -k -v --resolve "pollen.test:443:$HAPROXY_IP" https://pollen.test In the output, you should see the HAProxy charm is using the certificates signed by the self-signed-certificates charm. - ## Use a custom CA to sign certificates If you wish to sign the certificates used by the HAProxy charm using a custom CA @@ -101,5 +100,6 @@ earlier. HAPROXY_IP=$(juju status --format json | jq -r '.applications.haproxy.units."haproxy/0"."public-address"') curl -k -vv --resolve "pollen.test:443:$HAPROXY_IP" https://pollen.test ``` + In the output, you should see the HAProxy charm is using the custom CA: From 99c6c59bdf262a64d1bca7932c5ba2dfe9a0c3a0 Mon Sep 17 00:00:00 2001 From: Weii Wang Date: Wed, 8 Jul 2026 23:50:02 +0800 Subject: [PATCH 5/5] Apply suggestions from code review Co-authored-by: Erin Conley --- docs/how-to/use-self-signed-certificates.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/how-to/use-self-signed-certificates.md b/docs/how-to/use-self-signed-certificates.md index d33272b28..9be13bf82 100644 --- a/docs/how-to/use-self-signed-certificates.md +++ b/docs/how-to/use-self-signed-certificates.md @@ -17,7 +17,8 @@ charm and then use it to sign certificates for the HAProxy charm. To use the self-signed-certificates charm with the HAProxy charm, simply deploy the self-signed-certificates charm and integrate it with the HAProxy charm using -the `certificates` relation. +the `certificates` relation. This guide uses the Pollen charm as the backend application +requiring a certificate. ``` juju deploy haproxy --channel=2.8/stable @@ -53,7 +54,8 @@ CSR with your own CA using the `get-outstanding-certificate-requests` and To use the `manual-tls-certificates` charm with the HAProxy charm, deploy the manual-tls-certificates charm and integrate it with the HAProxy charm using -the `certificates` relation. +the `certificates` relation. This guide uses the Pollen charm as the backend application +requiring a certificate. ``` juju deploy haproxy --channel=2.8/stable