 We've talked about how to adapt when your DevOps needs outgrow your initial configurations, but what about when you have existing infrastructure you don't want to break when you're getting started? I think it's fair to say that most of us run workloads that exist outside of GitLab. Now maybe you'd like to manage those with or connect those to the platform, but you really don't want to be the person who breaks something that was already working. Our next speaker, Jesse Rushing, is an SRE. SRE is literally in her title, so while she wanted to connect her GitLab pipelines to existing production Kubernetes clusters, she was concerned. In this lightning talk, she will step you through those concerns and show you how she addressed them and ultimately emerged on the other side worry-free. Let's hear what she has to say. Welcome to Fear Not Integration. Today I'm going to be talking about how to connect an existing Kubernetes cluster to a GitLab CI CD project without interrupting your production applications. In today's lightning talk, I'm going to give you a quick introduction about who I am, a use case of when you would need to use this process, some prerequisites that you should already have set up before you begin, and then I'm going to give you a step-by-step walk-through of actually making the connection between your GitLab project repository and your Kubernetes cluster. I'm not going to talk about how to create a CI CD pipeline or run a deployment to your Kubernetes cluster. I'm really going to focus on the initial connection between the cluster and the project repository in doing it in a way that won't interrupt anything that might already be running on that cluster. My name is Jesse Rushing, and I'm a site reliability engineer for Coral by BoxMedia. Coral project is an open-source commenting application that is also available as a SaaS product. As a commenting tool, we are used by news organizations all around the world, and we are committed to improving online conversations, reducing harassment, and making commenting spaces safer for everyone. I manage our hosting infrastructure on Google Kubernetes Engine, and I've used the process that I'm about to share to automate my deployment pipelines using GitLab's CI CD. So when would you need to use this process? Well, it's a pretty common scenario that you don't have the luxury of setting everything up from scratch. If you already have an existing Kubernetes cluster that's running some production workloads, but you want to create a GitLab project with CI CD to automate your workload deployments, but you're afraid if I connect my GitLab project to my Kubernetes cluster, will GitLab replace or interrupt my running workloads? The first time that I wanted to set this up, I was very afraid that anything running on my cluster would be potentially overwritten or destroyed by GitLab once I connected things. And I can assure you that if you use this process, you can do this in such a way that you will make establish the initial connection, but not actually change any of the running workloads that are already existing on your Kubernetes cluster. So what do you need before you begin? Well, you need a workload running on Kubernetes. This could be any application or workload that is already up and running, and it can be running in any namespace on your cluster. If you're running everything in default, that's fine. No judgment. If you're running everything in multiple namespaces and you have isolated your staging and production and so on, that's also fine. You also probably already have an uptime check or something monitoring the workload. You want to have a way of validating that your workload hasn't been interrupted as you read through this process. In order to create the initial connection, you're also going to need some permissions in order to be able to configure your Kubernetes cluster. This could depend on your cloud provider or what infrastructure you're hosting that Kubernetes cluster on. But if you're on EKS, you're going to need administrator privileges. And if you're on GKE, you're going to need permissions to create cluster role bindings. The last thing you're going to need is a GitLab project repository that's not yet connected to Kubernetes. This could be your project repository that contains your application code, or it could be home charts in your Kubernetes yamls. It could also be an empty project repository that you haven't set up yet. At Coral, we've decoupled our application code from our deployment yamls and our Kubernetes yamls and our home charts, because our application code is open source and our Google Kubernetes engine infrastructure as code files are all internal. So next, we're going to go through the step-by-step walkthrough of actually making the initial connection. GitLab has some really great documentation that's available at this link here. And I'd highly recommend that you follow their steps in detail as you go through the process. I'm not going to cover every single step that they talk about, but just the important ones that you need to pay attention to when you're making a connection to an existing cluster that's already running things. Before I get into the first step, I want to talk about environments and namespaces for a moment. GitLab has a concept of environments. And you're going to find this inside of your GitLab project repository. And what you want to do is you want to be able to target each one of your Kubernetes namespaces as an environment on your CI CD yaml. So when you create that yaml and you create your jobs and you create your pipelines, you're going to want to be able to specify your Kubernetes namespaces as environments. In order to set this up correctly, there's a couple of configuration options that we need to make sure that we set. The first is the environment scope option. We're going to leave this defaulted to asterisk. So that all of the environments that we've created in GitLab will be available to our CI CD pipelines. The next one is there's a checkbox that we're going to make sure we check that's labeled namespace per environment. This is what's actually going to create the one-to-one relationship between your namespaces and your environments. So the first step is I actually like to create those environments before I begin, I said, by creating the initial connection. You don't actually have to do this first. You can create your environments after you've created the connection. And of course, you can always add more environments and namespaces down the road. But I like to do this part first. So you're going to find this option inside your GitLab project, and you're going to go to deployments, environments, and then use that blue New Environment button. And you just want to create one new environment for each project that already exists, sorry, for each namespace that already exists in your cluster. Next, you're going to start to create your connection. You're going to find this option inside your GitLab project under Infrastructure, Kubernetes Clusters, Integrate with Cluster Certificate, and then you want to make sure to select the Connect Existing Cluster option. This is going to open up a form where you can fill out some details about your cluster so that GitLab will be able to connect to it. The first is the cluster name, pretty easy. Then you're going to notice that environment scope option. You want to leave this set to asterisk so that all of your environments will be able to be accessible on your CI CD pipelines and will be able to connect and deploy to those namespaces on your cluster. For the rest of the details, we're going to need to run some kubectl commands in order to get the details from our cluster so we can populate them on the form. In order to get the cluster API URL, you're going to run this kubectl command. Now, your cluster API URL is the address or the location of your cluster on the internet so that GitLab will be able to find it and interact with it. Next, you're also going to need to get your cluster certificate. There's actually two commands you need to run here. The first one is just to get secrets, and then the next one, you're going to take the secret name for your default token secret, and you're going to drop that into the second command so that you can actually decode that secret and extract out your cluster certificate. Once you've got that value, just drop that into the form on GitLab. The next step is you're going to need to get a YAML file, which is available on the instructions that I linked earlier. This YAML file is going to contain the Kubernetes code for the cluster to create a service account and a cluster role binding. You need to create both the service account and the cluster role binding, and then you're going to need to get the authentication token for that service account that you've just created. You're going to save and then apply the YAML file to create the account, and then you're going to run this command to get the token. You're going to want to drop that authentication token onto the form in GitLab. At this point, you have actually modified your Kubernetes cluster, but you haven't changed anything except adding a user to the cluster so that GitLab will be able to connect with that user and eventually make changes. GitLab is not going to change anything unless you specify what you want it to change on your CI CD YAML. So as long as your project repository doesn't have a CI CD YAML yet, once you create that initial connection, there won't be anything for GitLab to change. The last part of the form is actually where the most important step is going to be, and that is that you need to uncheck the box that's called GitLab Managed Cluster. This is the setting that's going to tell GitLab to not take over and manage the namespaces and existing workloads that are already running on your cluster. And it's going to allow you to connect to the cluster in such a way that that cluster will now be available to use on your CI CD YAML in your pipelines and jobs, but it won't actually make any changes to your cluster. A couple of other things to note here. If you are using RBAC on your cluster, if your cluster has RBAC enabled, go ahead and leave that box checked. However, if you have disabled RBAC on your Kubernetes cluster for security reasons, you will need to uncheck this box. Also note that the namespace per environment setting that I mentioned earlier is listed here, and we've left that box checked. Leaving that box checked will create a one-to-one relationship between the namespaces and the environments. Finally, you're going to go ahead and click that Add Kubernetes cluster button, and after a few minutes, the initial connection will be established. At that point, you'll be able to see details about your cluster in GitLab, although you won't have the full integration that you would have if you were using the GitLab Managed Cluster option. That's OK because also GitLab won't be managing your cluster and trying to replace your workloads. So the result of establishing this initial connection is now you can go and create your CI CD pipelines, you can have build, test, and deployment stages, and you can target your namespaces when you write those pipeline commands. You also will be able to view your environments in GitLab, and once you've started running those CI CD pipelines, you'll be able to see when they were last deployed. Finally, this has created the connection so you can enable other cluster integrations between GitLab and your Kubernetes cluster. So to summarize, you want to make sure that you link your environment to each namespace. You want to use the Connect Existing Cluster option and uncheck the GitLab Managed Cluster box, and then you want to create your CI CD jobs targeting each namespace in your cluster. It has been an honor to present at GitLab Commit 2021. Thank you.