diff --git a/guides/troubleshooting/registry.md b/guides/troubleshooting/registry.md new file mode 100644 index 000000000..70cfdb99b --- /dev/null +++ b/guides/troubleshooting/registry.md @@ -0,0 +1,61 @@ +--- +title: Image registry troubleshooting +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: + +```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. 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 you're using will be HTTPS. + +## Troubleshooting steps + +- 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 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 + ``` + +- 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 you've created the self-signed certificate secret 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. diff --git a/manifest.json b/manifest.json index 97bf42005..f7926caf6 100644 --- a/manifest.json +++ b/manifest.json @@ -359,10 +359,13 @@ "navigable": false, "children": [ { - "path": "./guides/troubleshooting/inotify-watch-limits.md" + "path": "./guides/troubleshooting/docker-problems.md" }, { - "path": "./guides/troubleshooting/docker-problems.md" + "path": "./guides/troubleshooting/registry.md" + }, + { + "path": "./guides/troubleshooting/inotify-watch-limits.md" } ] } 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: