github.com/wmuizelaar/kpt@v0.0.0-20221018115725-bd564717b2ed/site/guides/namespace-provisioning-ui.md (about) 1 # Namespace provisioning using UI 2 3 In this guide, we will learn how to create a kpt package from scratch using 4 Config as Data UI. We will also learn how to enable customization of the package 5 with minimal steps for package consumers and deploy the package to a Kubernetes 6 cluster. 7 8 ## What package are we creating ? 9 10 Onboarding a new application or a micro-service is a very common task for a 11 platform team. It involves provisioning a dedicated namespace (and other 12 associated resources) where all resources that belong to the application reside. 13 In this guide, we will create a package that will be used for provisioning a 14 namespace. 15 16 ## Prerequisites 17 18 Before we begin, ensure that you can access the Config as Data UI. The UI is 19 provided as a [Backstage](https://backstage.io) plugin and can be accessed at 20 `[BACKSTAGE_BASE_URL]/config-as-data`. 21 22 _If you don't have a UI installed, follow the steps in the 23 [UI installation guide](guides/porch-ui-installation.md) to install the UI._ 24 25 You will also need two new git repositories. The first repository will be where 26 the reusable kpt packages will live. The second repository is where the 27 instances of packages that will be deployed to a Kubernetes cluster will live. 28 Users will create deployable packages from the packages in the blueprint repo. 29 30 ## Repository Registration 31 32 ### Registering blueprint repository 33 34 Start by clicking the `Register Repository` button in the upper right corner to 35 register a blueprint repository. Enter the following details in the Register 36 Repository flow: 37 38 - In `Repository Details`, the Repository URL is the clone URL from your 39 repository. Branch and directory can be left blank. Branch will default to 40 `main` and directory will default to `/`. 41 - In `Repository Authentication`, you`ll need to use the GitHub Personal Access 42 Token (unless your repository allows for unauthenticated writes). Github 43 Personal Access Tokens can be created at https://github.com/settings/tokens, 44 and must include the 'repo' scope. 45 - In `Repository Content`, select `Team Blueprints`. 46 47 Once the repository is registered, use the breadcrumbs (upper left) to navigate 48 back to the Repositories view. 49 50 ### Registering deployment repository 51 52 Start by clicking the `Register Repository` button in the upper right corner to 53 register a deployment repository. Enter the following details in the Register 54 Repository flow: 55 56 - In `Repository Details`, the Repository URL is the clone URL from your 57 repository. Branch and Directory can be left blank. Branch will default to 58 `main`, and directory will default to `/`. 59 - In `Repository Authentication`, either create a new secret, or optionally 60 select the same secret in the Authentication Secret dropdown you created for 61 registering blueprint repository. 62 - In `Repository Content`, select Deployments. 63 64 Once the repository is created, use the breadcrumbs (upper left) to navigate 65 back to the Repositories view. 66 67 ## Creating a Blueprint from scratch 68 69 Now that we have our repositories registered, we are ready to create our first 70 blueprint using the UI. 71 72 - On the Repositories Page, click the row of the team blueprint repository where 73 you want to add the new blueprint to. 74 - Clicking the row will take you to a new screen where you can see the 75 packages/blueprints in the selected repository. If this is a new repository, 76 the list will be empty. 77 - Click the `Add Team Blueprint` button in the upper right corner to create a 78 new team blueprint. 79 - In `Add Team Blueprint`, create a new team blueprint from scratch with the 80 name `simplens`. 81  82 - After completing the above flow, you`ll be taken to your newly created 83 blueprint (see screenshot below). Here you will have a chance to add, edit, 84 and remove resources and functions. 85  86 - Clicking any of the resources on the table (currently the `Kptfile` and 87 `ConfigMap`) will show the resource viewer dialog where you can see quick 88 information for each resource and view the yaml for the resource. 89 - On the blueprint (see the above screenshot), click `Edit` to be able to edit 90 the blueprint. After clicking `Edit`, you should see this screen where you 91 have an option to add new resources. 92  93 - Using the `Add Resource` button, add a new Namespace resource. Name the 94 namespace `example`. 95 - Click the Kptfile resource and add a new mutator 96 - Search for `namespace` and select `set-namespace` with the latest version 97 available for selection. 98 - Select `ConfigMap: kptfile.kpt.dev` for the function config 99 - By setting both of these values, anytime the blueprint is rendered (for 100 instance, on save or when a deployable instance of the blueprint is 101 created), the namespace will be set to the name of the package. 102 - Using the `Add Resource` button, add a new Role Binding resource 103 - Name the resource `app-admin` 104 - In Role Reference, select `Cluster Role` and set `app-admin` as the name 105 - Click Add Subject, and in the newly added subject, select `Group` and set 106 the name to `example.admin@bigco.com`. 107 - Using the `Add Resource` button, add a new Apply Replacements resource. 108 - Name the resource `update-rolebinding` 109 - In Source, select `ConfigMap: kptfile.kpt.dev` as the source resource and 110 set `data.name: example` as source path 111 - In Target, select `RoleBinding: app-admin` as the target resource and set 112 `subjects.0.name: example.admin@bigco.com` as the target path. Select 113 `Partial Value` as the replace value option, with `period (.)` as the 114 delimiter selecting `example` to replace. 115 - Click the Kptfile resource to see the `apply-replacements` mutator has been 116 added automatically by the previous step 117 - The UI knows to add this mutator anytime a an `ApplyReplacements` resource 118 is added 119 - Screenshot of the Kptifle showing the two mutators 120  121 - Using the `Add Resource` button, add a new Resource Quota resource 122 - Name the resource `base` 123 - Set Max CPU Requests to `40` and Max Memory Requests to `40G` 124 - After you are done with the above, you should have the following resources 125  126 - Clicking `Save` will save the resources, apply the mutator, and take you back 127 to the blueprint screen you started on. Note that the namespace has been 128 updated on the resources from the `set-namespace` mutator. 129  130 - Click the individual resources to see the first class editors. 131 - Click Propose to propose the blueprint (button will change to Approve) 132 - Click Approve to approve the blueprint 133 - Using the breadcrumbs, click back to view your blueprints repository - here 134 you should see the blueprint you just created has been finalized. 135  136 137 So, with that, we created a blueprint from scratch and published it in a team 138 blueprint repository. You should be able to see the blueprint by viewing the 139 `git` repository directly well. 140 141 ## Create a deployable instance of a blueprint 142 143 In this section, we will walk through the steps of creating a deployable 144 instance of a blueprint. 145 146 - Starting from the team blueprints repository, you should see the `simplens` 147 blueprint created above. 148  149 - Click the `simplens` blueprint. 150  151 - Click the `Clone` button in the upper right corner to take you to the clone 152 flow. For Action, select 153 `Create a new deployment by cloning the simplens team blueprint` and name the 154 deployment `backend`. 155  156 - Completing the flow will add the package to your deployments repository. Note 157 that the namespace across all the namespace scoped resources have been updated 158 to the name of the package. 159  160 - Click the `Diff` button for the `RoleBinding app-admin` resource. Here you’ll 161 see the differences between this resource and the same resource in the 162 upstream `simplens` team blueprint. In addition to the namespace being 163 updated, the binding has also been updated from the Apply Replacements 164 resource. 165  166 - After closing the diff dialog, using the breadcrumbs, click back the 167 deployments view to see your new deployment is added in Draft status. 168  169 - Click into the backend deployment and move the deployment to Proposed, then 170 Published by approving the deployment. Optionally, before moving the 171 deployment to Proposed, you can make changes to the deployment by 172 adding/removing/updating resources. 173 - Once the deployment is published, click `Create Sync` to have `Config Sync` 174 sync the deployment to the Kubernetes cluster. 175  176 - After a few seconds, you`ll see the Sync status update in the upper right-hand 177 corner. 178  179 - If you navigate back to the `deployment` repository, you will see `sync` 180 status next to each deployment instance. 181  182 183 So, this completes our end-to-end workflow of creating a blueprint from scratch 184 and deploying it to a Kubernetes cluster using the Config as Data UI.