From 8e45723317c5a9722f404fa2009cce7f70f04873 Mon Sep 17 00:00:00 2001 From: Eric Paulsen Date: Tue, 22 Jun 2021 15:04:22 -0500 Subject: [PATCH 1/6] add registry troubleshooting steps --- guides/troubleshooting/registry.md | 59 ++++++++++++++++++++++++++++++ setup/air-gapped/infrastructure.md | 2 +- 2 files changed, 60 insertions(+), 1 deletion(-) create mode 100644 guides/troubleshooting/registry.md diff --git a/guides/troubleshooting/registry.md b/guides/troubleshooting/registry.md new file mode 100644 index 000000000..60c51d9d4 --- /dev/null +++ b/guides/troubleshooting/registry.md @@ -0,0 +1,59 @@ +--- +title: Image registry troubleshooting +description: Learn how to resolve issues related to connecting an image registry +--- + +When configuring Coder to use a local image registry in an air-gapped network, +you may encounter an error similar +to the following: + +```console +An error occurred while submitting + +unable to ping registry for 'new transport: Get "https://registry-url.org": x509: +certificate signed by unknown authority +``` + +## Why this happens + +The local registry you are configuring is expecting a valid certificate to authenticate +the connection with Coder. If you do not have a certificate configured, or if there +is an issue with the certificate itself, you will receive this error. + +> Coder uses Docker's Registry 2.0 implementation, which supports self-signed +> certificates and assumes that the protocol used will be HTTPS. + +## Troubleshooting steps + +- If the local registry has not been created, and the self-signed cert has not been +generated, [please see our documentation](../../setup/air-gapped/infrastructure.md) +on setting these up. + +- Check to see if your `registry.crt` file is stored in the correct location on +each of your Kubernetes nodes. Depending upon your Linux distribution and container +runtime, it may be in one of the following places: + +```console +/usr/local/share/ca-certificates/registry.crt +/etc/docker/certs.d/${REGISTRY_DOMAIN_NAME}/ca.crt +/etc/ssl/certs/registry.crt +/etc/pki/tls/registry.crt +``` + +- If your cluster uses containerd, ensure the following patch has been applied to +the `/etc/containerd/config.toml` file: + +```console +[plugins."io.containerd.grpc.v1.cri".registry.configs."$REGISTRY_DOMAIN_NAME".tls] + insecure_skip_verify = true +``` + +- Ensure that the self-signed certificate secret has been created in your Kubernetes +cluster: + +```console +kubectl -n coder get secret local-registry-cert -o yaml +``` + +If none of these steps resolve the issue, please [contact us](https://coder.com/contact) +for further support. \ No newline at end of file diff --git a/setup/air-gapped/infrastructure.md b/setup/air-gapped/infrastructure.md index 2d940f454..9d4afa4ee 100644 --- a/setup/air-gapped/infrastructure.md +++ b/setup/air-gapped/infrastructure.md @@ -54,7 +54,7 @@ docker run -d -p 443:5000 \ ## Configuring the Kubernetes Node -Before the Kubernetes node can accept run local images, it needs to consider the +Before the Kubernetes node can accept local images, it needs to consider the new `registry.crt` file as trusted. The specific locations and methods to store and trust the certificate vary depending on the Linux distribution and the container runtime, but here is a partial list to help you get started: From ba4a937ee145e6423dcee5fed04efa55bd336abe Mon Sep 17 00:00:00 2001 From: Eric Paulsen Date: Tue, 22 Jun 2021 15:10:59 -0500 Subject: [PATCH 2/6] lint --- guides/troubleshooting/registry.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/troubleshooting/registry.md b/guides/troubleshooting/registry.md index 60c51d9d4..0690814e0 100644 --- a/guides/troubleshooting/registry.md +++ b/guides/troubleshooting/registry.md @@ -56,4 +56,4 @@ kubectl -n coder get secret local-registry-cert -o yaml ``` If none of these steps resolve the issue, please [contact us](https://coder.com/contact) -for further support. \ No newline at end of file +for further support. From 3ea374316d500f3d6ce1fb1932e5b27f31abb6ed Mon Sep 17 00:00:00 2001 From: Eric Paulsen Date: Tue, 22 Jun 2021 15:23:16 -0500 Subject: [PATCH 3/6] add to manifest --- manifest.json | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/manifest.json b/manifest.json index 97bf42005..96255e216 100644 --- a/manifest.json +++ b/manifest.json @@ -363,7 +363,11 @@ }, { "path": "./guides/troubleshooting/docker-problems.md" + }, + { + "path": "./guides/troubleshooting/registry.md" } + ] } ] From 8a4c95e91c3b5a36f243b751b1a1366355252cf6 Mon Sep 17 00:00:00 2001 From: Eric Paulsen Date: Tue, 22 Jun 2021 15:24:10 -0500 Subject: [PATCH 4/6] json spacing --- manifest.json | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/manifest.json b/manifest.json index 96255e216..1962ae3ad 100644 --- a/manifest.json +++ b/manifest.json @@ -366,8 +366,7 @@ }, { "path": "./guides/troubleshooting/registry.md" - } - + } ] } ] From e2179731c892f2ebfcd605fa186a53d60473a9c3 Mon Sep 17 00:00:00 2001 From: Katie Horne Date: Wed, 23 Jun 2021 10:58:28 -0500 Subject: [PATCH 5/6] Update manifest; lint --- guides/troubleshooting/registry.md | 34 +++++++++++++++--------------- manifest.json | 8 +++---- 2 files changed, 21 insertions(+), 21 deletions(-) diff --git a/guides/troubleshooting/registry.md b/guides/troubleshooting/registry.md index 0690814e0..a11103beb 100644 --- a/guides/troubleshooting/registry.md +++ b/guides/troubleshooting/registry.md @@ -1,11 +1,10 @@ --- title: Image registry troubleshooting -description: Learn how to resolve issues related to connecting an image registry +description: Learn how to resolve issues connecting to an image registry. --- When configuring Coder to use a local image registry in an air-gapped network, -you may encounter an error similar -to the following: +you may encounter an error similar to the following: ```console An error occurred while submitting @@ -16,22 +15,23 @@ certificate signed by unknown authority ## Why this happens -The local registry you are configuring is expecting a valid certificate to authenticate -the connection with Coder. If you do not have a certificate configured, or if there -is an issue with the certificate itself, you will receive this error. +The local registry you are configuring is expecting a valid certificate to +authenticate the connection with Coder. If you do not have a certificate +configured, or if there is an issue with the certificate itself, you will +receive this error. > Coder uses Docker's Registry 2.0 implementation, which supports self-signed > certificates and assumes that the protocol used will be HTTPS. ## Troubleshooting steps -- If the local registry has not been created, and the self-signed cert has not been -generated, [please see our documentation](../../setup/air-gapped/infrastructure.md) -on setting these up. +- If the local registry has not been created, and the self-signed cert has not + been generated, [please see our + documentation](../../setup/air-gapped/infrastructure.md) on setting these up. - Check to see if your `registry.crt` file is stored in the correct location on -each of your Kubernetes nodes. Depending upon your Linux distribution and container -runtime, it may be in one of the following places: + each of your Kubernetes nodes. Depending upon your Linux distribution and + container runtime, it may be in one of the following places: ```console /usr/local/share/ca-certificates/registry.crt @@ -40,20 +40,20 @@ runtime, it may be in one of the following places: /etc/pki/tls/registry.crt ``` -- If your cluster uses containerd, ensure the following patch has been applied to -the `/etc/containerd/config.toml` file: +- If your cluster uses containerd, ensure the following patch has been applied + to the `/etc/containerd/config.toml` file: ```console [plugins."io.containerd.grpc.v1.cri".registry.configs."$REGISTRY_DOMAIN_NAME".tls] insecure_skip_verify = true ``` -- Ensure that the self-signed certificate secret has been created in your Kubernetes -cluster: +- Ensure that the self-signed certificate secret has been created in your + Kubernetes cluster: ```console kubectl -n coder get secret local-registry-cert -o yaml ``` -If none of these steps resolve the issue, please [contact us](https://coder.com/contact) -for further support. +If none of these steps resolve the issue, please [contact +us](https://coder.com/contact) for further support. diff --git a/manifest.json b/manifest.json index 1962ae3ad..f7926caf6 100644 --- a/manifest.json +++ b/manifest.json @@ -358,15 +358,15 @@ "path": "./guides/troubleshooting/index.md", "navigable": false, "children": [ - { - "path": "./guides/troubleshooting/inotify-watch-limits.md" - }, { "path": "./guides/troubleshooting/docker-problems.md" }, { "path": "./guides/troubleshooting/registry.md" - } + }, + { + "path": "./guides/troubleshooting/inotify-watch-limits.md" + } ] } ] From 88ae6bf21d30412fd7e480e834b9c8946f0b4cb6 Mon Sep 17 00:00:00 2001 From: Katie Horne Date: Wed, 23 Jun 2021 13:33:52 -0500 Subject: [PATCH 6/6] Edit text --- guides/troubleshooting/registry.md | 48 ++++++++++++++++-------------- 1 file changed, 25 insertions(+), 23 deletions(-) diff --git a/guides/troubleshooting/registry.md b/guides/troubleshooting/registry.md index a11103beb..70cfdb99b 100644 --- a/guides/troubleshooting/registry.md +++ b/guides/troubleshooting/registry.md @@ -16,44 +16,46 @@ certificate signed by unknown authority ## Why this happens The local registry you are configuring is expecting a valid certificate to -authenticate the connection with Coder. If you do not have a certificate -configured, or if there is an issue with the certificate itself, you will -receive this error. +authenticate the connection with Coder. You will receive this error if: + +- You do not have a certificate +configured +- There is an issue with the certificate itself > Coder uses Docker's Registry 2.0 implementation, which supports self-signed -> certificates and assumes that the protocol used will be HTTPS. +> certificates and assumes that the protocol you're using will be HTTPS. ## Troubleshooting steps -- If the local registry has not been created, and the self-signed cert has not - been generated, [please see our +- If you haven't created the local registry, and you haven't generated the + self-signed certificate, [please see our documentation](../../setup/air-gapped/infrastructure.md) on setting these up. - Check to see if your `registry.crt` file is stored in the correct location on each of your Kubernetes nodes. Depending upon your Linux distribution and - container runtime, it may be in one of the following places: + container runtime, it may be in any of the following locations: -```console -/usr/local/share/ca-certificates/registry.crt -/etc/docker/certs.d/${REGISTRY_DOMAIN_NAME}/ca.crt -/etc/ssl/certs/registry.crt -/etc/pki/tls/registry.crt -``` + ```console + /usr/local/share/ca-certificates/registry.crt + /etc/docker/certs.d/${REGISTRY_DOMAIN_NAME}/ca.crt + /etc/ssl/certs/registry.crt + /etc/pki/tls/registry.crt + ``` -- If your cluster uses containerd, ensure the following patch has been applied +- If your cluster uses `containerd`, ensure the following patch has been applied to the `/etc/containerd/config.toml` file: -```console -[plugins."io.containerd.grpc.v1.cri".registry.configs."$REGISTRY_DOMAIN_NAME".tls] - insecure_skip_verify = true -``` + ```console + [plugins."io.containerd.grpc.v1.cri".registry.configs."$REGISTRY_DOMAIN_NAME".tls] + insecure_skip_verify = true + ``` -- Ensure that the self-signed certificate secret has been created in your - Kubernetes cluster: +Ensure that you've created the self-signed certificate secret in your Kubernetes +cluster: -```console -kubectl -n coder get secret local-registry-cert -o yaml -``` + ```console + kubectl -n coder get secret local-registry-cert -o yaml + ``` If none of these steps resolve the issue, please [contact us](https://coder.com/contact) for further support.