Cloud deploy docs are confusing and overlapping
Problem
The following docs are somewhat hidden, have overlapping content, have missing content, and not clearly named.
-
Cloud deploy
, which is about AWS and GitLab CI/CD, but also talks about deploying to ECR, EC2, and EKS. -
Deploy to ECS
- This doc has AWS steps and screenshots, and needs to be updated. -
Requirements for Auto DevOps
- This page has sections for ECS and EC2... Tutorial: Use Auto DevOps to deploy an application to Google Kubernetes Engine
Also need to update this page: https://docs.gitlab.com/ee/topics/release_your_application.html
Approach
- Go through the pages and clean them up. Clarify and pare down the language, and get a better understanding of what's on each.
- Compare the pages and figure out the best way to combine/de-duplicate and link to one another.
- Update the docs left nav.
- Clean up all of the references to these docs from other pages.
- Move files into more appropriate file locations and redirect from the old locations. (And update nav to have new links.)
Details
Further details from @cwoolley-gitlab
:
There is no reference to these pages at all in the actual Auto Devops docs, which has a "quick start" section: https://docs.gitlab.com/ee/topics/autodevops/#quick-start, which points to the "Tutorial".
But that "Tutorial" (file named quick_start_guide.html
) under that section is specific to K8S, not ECS (https://docs.gitlab.com/ee/topics/autodevops/quick_start_guide.html).
For ECS, there's just a small mention and link back in the top level page under https://docs.gitlab.com/ee/topics/autodevops/#quick-start, which says You can also follow the quick start for the general steps, but deploy to AWS ECS instead.
.
Which links to the "Requirements" subsection, which is not a Tutorial or a Guide at all: https://docs.gitlab.com/ee/topics/autodevops/requirements.html#auto-devops-requirements-for-amazon-ecs
And when I was initially trying to set this up, I just kept going between all those pages under https://docs.gitlab.com/ee/topics/autodevops/, and had no idea that the guide under https://docs.gitlab.com/ee/ci/cloud_deployment/ecs/quick_start_guide.html existed, which is actually the best one with some important info that isn't under topics/autodevops
Also, there doesn't seem to be any "guides" for K8s Auto DevOps deploys under ci/cloud_deployment
, like there is for ci/cloud_deployment/ecs
. Just the K8s one under ee/topics/autodevops/quick_start_guide
Finally, the menu structure does not match the directory structure, which is also confusing in trying to understand what higher-level context is relevant or not. For example, /ci/cloud_deployment/
is a page called "Deploy to AWS", and ci/cloud_deployment/ecs/quick_start_guide.html
(a subdirectory down) is at the same menu/navigation level called "Deploy to ECS".
Considering all that, there's at least 2-4 things that are "guides" or "tutorials" related to Auto DevOps; they have varying degrees of useful information, none of it all in one place; and there's ECS-specific stuff mixed in with irrelevant/incorrect K8s-specific stuff in some places.
My suggestion would be to try to:
- Consolidate all of these instructions / guides / quick starts under a single place, as a single cohesive set of guide.
- I would ideally put this guide with the rest of the Auto DevOps docs under
topics/autodevops
. If it's kept underci/cloud_deployment
, there should be very prominent links (probably multiple) to it from relevant pages undertopics/autodevops
, so other people don't miss it like I did. But preferably I'd like to see theci/cloud_deployment
ECS-specific stuff go away and be replaced with redirects or brief descriptions with links to full info undertopics/autodevops
(which aligns more with the following points). - There should be a clear separation of the ECS-specific stuff from the K8s-specific stuff. Ideally this would be under separate subdirectories (wherever it ends up living) named
ecs
/kubernetes
, with any common info (such as AWS creds/login instructions) in separate linked pages to avoid duplication. - This clear separation and reorg also sets us up for new future Auto DevOps support for different deployment methods, such as Heroku.