diff --git a/docs/debugging-install.md b/docs/debugging-install.md new file mode 100644 index 000000000..7969f1bcd --- /dev/null +++ b/docs/debugging-install.md @@ -0,0 +1,59 @@ +# Debugging Installation Issues + +## General + +### `invalid configuration: no configuration has been provided` +This typically means that no `kubeconfig` file can be found for the Ark client to use. Ark looks for a kubeconfig in the +following locations: +* the path specified by the `--kubeconfig` flag, if any +* the path specified by the `$KUBECONFIG` environment variable, if any +* `~/.kube/config` + +### Backups or restores stuck in `New` phase +This means that the Ark controllers are not processing the backups/restores, which usually happens because the Ark server is not running. Check the pod description and logs for errors: +``` +kubectl -n heptio-ark describe pods +kubectl -n heptio-ark logs deployment/ark +``` + + +## AWS + +### `NoCredentialProviders: no valid providers in chain` +This means that the secret containing the AWS IAM user credentials for Ark has not been created/mounted properly +into the Ark server pod. Ensure the following: +* The `cloud-credentials` secret exists in the Ark server's namespace +* The `cloud-credentials` secret has a single key, `cloud`, whose value is the contents of the `credentials-ark` file +* The `credentials-ark` file is formatted properly and has the correct values: + + ``` + [default] + aws_access_key_id= + aws_secret_access_key= + ``` +* The `cloud-credentials` secret is defined as a volume for the Ark deployment +* The `cloud-credentials` secret is being mounted into the Ark server pod at `/credentials` + + +## Azure + +### `Failed to refresh the Token` or `adal: Refresh request failed` +This means that the secrets containing the Azure service principal credentials for Ark has not been created/mounted +properly into the Ark server pod. Ensure the following: +* The `cloud-credentials` secret exists in the Ark server's namespace +* The `cloud-credentials` secret has seven keys and each one has the correct value (see [setup instructions](0)) +* The `cloud-credentials` secret is defined as a volume for the Ark deployment +* The `cloud-credentials` secret is being mounted into the Ark server pod at `/credentials` + + +## GCE/GKE + +### `open credentials/cloud: no such file or directory` +This means that the secret containing the GCE service account credentials for Ark has not been created/mounted properly +into the Ark server pod. Ensure the following: +* The `cloud-credentials` secret exists in the Ark server's namespace +* The `cloud-credentials` secret has a single key, `cloud`, whose value is the contents of the `credentials-ark` file +* The `cloud-credentials` secret is defined as a volume for the Ark deployment +* The `cloud-credentials` secret is being mounted into the Ark server pod at `/credentials` + +[0]: azure-config#credentials-and-configuration \ No newline at end of file diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index 45e2eba56..5884ddf7e 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -2,11 +2,14 @@ These tips can help you troubleshoot known issues. If they don't help, you can [file an issue][4], or talk to us on the [Kubernetes Slack team][25] channel `#ark-dr`. +* [Debug installation/setup issues][2] + * [Delete namespaces and backups][0] * [Debug restores][1] [0]: debugging-deletes.md [1]: debugging-restores.md +[2]: debugging-install.md [4]: https://github.com/heptio/ark/issues [25]: http://slack.kubernetes.io/ \ No newline at end of file