Document how to solve special characters breaking container registry
Problem to solve
The GitLab Container Registry allows users to build, push and share docker images/tags. However, if a user has special characters in either their group or project name and clicks on the 'Registry' section of their project, they will receive a 500 error and no explanation why. And, if a user has a branch name that includes special characters and attempts to build an image from GitLab's CI/CD product, it also fails on connection.
The root cause of this is that we validate registry paths against a Docker Distribution repository path regexp. And the below special characters result in an invalid path.
- Leading underscore
- Trailing hyphen/dash
- Double hyphen/dash
Intended users
Proposal
Document a solution for users that encounter an error loading the 'Registry' page due to special characters in their group, project or branch name. The solution, including sample scripts will be available on the 'Registry' page in the case of a 500 error due to naming conventions.
Design
If the user arrives at the Registry page and there are no registries to display, the users will see an empty state linking them to additional information about how to set up their registry:
If the user has special characters in their group, project or branch name, the user will see an error screen linking them to documentation describing how to fix the error:
Further details
Use cases
From the UI
- A user has one of the aforementioned special characters in their group or project name and from the UI navigates to the 'Registry' page.
- The user lands on an empty state page and sees that there is an error connecting to Docker Registry due to the use of special characters in their group or project name. We link to a troubleshooting article that walks the user through how to fix the issue.
- The user reads the help article, discovers the problem and fixes it.
- The user reloads or navigates back to the 'Registry' page, which is now able to connect to Docker Registry. (They'd see either the documentation on getting started, or their registry depending on if it was a new group/project or an existing one where the name was changed.)
From the CLI
- A user from the command line attempts to run
docker push
to their GitLab Registry and it fails due to the naming convention causing an invalid path. - The gets frustrated and opens up the GitLab documentation for the Container Registry.
- They scroll down to Troubleshooting the Container Registry and see a section about invalid path errors and read the guide on how to remediate the issue.
- They fix the issue and there is much rejoicing.
From CI/CD
- A user who has created a branch name with any of the mentioned special characters, or renamed their project or group to include those characters, runs a pipeline job.
- The job uses branch names to tag containers which get pushed to the docker registry. e.g.
build:
variables:
IMAGE: $CI_REGISTRY_IMAGE/$CI_COMMIT_REF_SLUG
script:
- docker login -u gitlab-ci-token -p $CI_JOB_TOKEN registry.gitlab.com
- docker build --build-arg RAILS_ENV=production --target production --tag "$IMAGE:latest" .
- docker push "$IMAGE:latest"
- The pipeline fails and returns an error of
denied: requested access to the resource is denied
- The gets frustrated and opens up the GitLab documentation for the Container Registry.
- They scroll down to Troubleshooting the Container Registry and see a section about invalid path errors and read the guide on how to remediate the issue.
- They fix the issue and there is much rejoicing.
API
- Since the API uses Project_ID and not project/group path, this is not a problem.
Why documentation, why not address the root problem?
Good question. This is a common problem and can be really frustrating on behalf of our users. But, there is no good solution. Forcing naming conventions feels heavy handed and doesn't address the many existing use cases. Providing a warning to users only really impacts the UI. We would still be left with resolving the API, CLI, and CI/CD. A clear guide to solving the issue will help users solve the problem, without having to wait for sweeping changes.
Permissions and Security
There are no permissions changes for this issue.
Documentation
- Container Registry User Guide
- Container Registry Admin documentation (Here we can add a note about the special characters and maybe suggest a push rule that will prevent users at the instance level.
Testing
- It will be important to think about solving the problem for group, project and branches for new and existing projects.
What does success look like, and how can we measure that?
Success looks like we are able to help our users solve this known problem with clear, intuitive documentation. We can measure success by the amount of issues raised detailing this problem.