I recently joined a project where the customer owns several products, development was outsourced, infrastructure responsibilities moved between multiple vendors, and a low-code platform was added to the mix. The result is a confusing environment with significant technical debt, neglected on-premises systems, outdated cloud resources, and very little reliable documentation.
Much of the infrastructure is managed through Jenkins jobs that destroy and recreate resources. Some of the logic may be repeatable, but it is difficult to tell whether the jobs are genuinely idempotent or simply happen to work under certain conditions. We are beginning to move these processes to GitLab while also modernizing application deployments, migrating some IIS workloads toward Kubernetes, improving CI/CD and security, and upgrading Kubernetes versions before they reach end of life.
The difficult part is prioritization and planning. I have never architected a migration of this size or for a team this large. I like diagrams and process documentation, but the scope is so broad that I struggle to know where to start or how much detail to include.
What tools or planning methods have helped you understand an inherited environment, prioritize migration work, and design a realistic target architecture without getting lost in unnecessary detail?
4 Answers
Use the Kubernetes end-of-life dates as a forcing function, since those deadlines are objective and cannot be postponed indefinitely. Beyond that, start with a thin but reliable platform or one representative service. Implement the desired delivery, observability, security, rollback, and documentation practices there, then use it as a repeatable pattern for the remaining workloads. Also classify what you find as business logic, configuration, integration glue, or dead weight. Understanding what each surviving component does in plain language will make architectural decisions much easier.
Start by building an inventory before designing the migration. List the applications, services, servers, environments, owners, deployment paths, dependencies, and any external deadlines. Also identify what is actually used versus what is merely running. Inherited environments often contain a surprising amount of abandoned infrastructure, and removing or isolating that noise can make the real problem much smaller.
Separate the current state from the target state. Create one rough diagram of how things work today, then a second diagram showing where you want to end up. For the diagrams, use layers: keep one high-level architecture view, then create smaller diagrams for individual applications and migration workstreams. A visual tool such as draw.io works well, but even a whiteboard photographed and documented is enough to begin. Once the target state is clear, rank work by business risk, dependencies, ease of cutover, and deadlines.
Be cautious about treating the move from Jenkins to GitLab as the solution by itself. The important question is what those jobs do, not which system triggers them. Inventory every operational job, determine whether it runs against production, document what it changes, and test whether it is truly safe to run repeatedly. A destructive rebuild process has a much larger blast radius than an ordinary failed deployment, so migrate and improve those jobs deliberately rather than copying them wholesale.
That layered approach is exactly what I was missing. I was trying to make one diagram contain the entire environment, which quickly became useless.