|
| 1 | +# Namespace provisioning example using UI |
| 2 | + |
| 3 | +In this guide, we will use the package orchestration UI to: |
| 4 | + |
| 5 | +- Register blueprint and deployment repositories |
| 6 | +- Create a `kpt` package from scratch in blueprint repo |
| 7 | +- Create a deployable instance of the `kpt` package |
| 8 | +- Deploy the package in a kubernetes cluster |
| 9 | + |
| 10 | +## Prerequisites |
| 11 | + |
| 12 | +Before we begin, ensure that you are able to access the UI for `package orchestraction`. |
| 13 | +The UI is provided as `Backstage` plugin and can be accessed at `[BACKSTAGE_BASE_URL]/config-as-data`. |
| 14 | + |
| 15 | +*If you don't have a UI installed, follow the steps in [UI installation guide](guides/porch-ui-installation.md) |
| 16 | +to install the UI.* |
| 17 | + |
| 18 | +## Repository Registration |
| 19 | + |
| 20 | +Ignore this section if you already have `blueprint` and `deployment` repo registered |
| 21 | +with `porch`. |
| 22 | + |
| 23 | +### Registering blueprint repository |
| 24 | + |
| 25 | +To register a blueprint repo, start by clicking `Register Repository` button in |
| 26 | +the upper right corner. Enter the following details in the Register Repository flow: |
| 27 | + |
| 28 | +- In Repository Details, the Git URL is the clone url from your repository (i.e. https://github.com/platkrm/chris-blueprints.git). |
| 29 | +Branch and directory can be left blank. Branch will default to `main` and |
| 30 | +directory will default to `/`. |
| 31 | +- In Repository Authentication, you’ll need to use the GitHub Personal Access Token |
| 32 | +(unless your repository allows for unauthenticated writes). |
| 33 | +Create a new secret for the Personal Access Token as directed by the flow. |
| 34 | +- In Repository Content, be sure to select Blueprints. |
| 35 | + |
| 36 | +Once the repository is registered, use the breadcrumbs (upper left) to navigate |
| 37 | +back to the Repositories view. |
| 38 | + |
| 39 | +### Registering deployment repository |
| 40 | + |
| 41 | +To register a deployment repo, start by clicking `Register Repository` button in |
| 42 | +the upper right corner. Enter the following details in the Register Repository flow: |
| 43 | + |
| 44 | +- In Repository Details, the `git URL` is the clone url from your repository (i.e. https://github.com/platkrm/chris-deployments.git). |
| 45 | +`Branch` and `directory` can be left blank. Branch will default to `main` and |
| 46 | +directory will default to `/`. |
| 47 | +- In Repository Authentication, either create a new secret, or optionally, |
| 48 | +select the same secret in the Authentication Secret dropdown you created for |
| 49 | +registering blueprint repo. |
| 50 | +- In Repository Content, be sure to select `Deployments`. |
| 51 | +- In Upstream Repository, select from the already registered Blueprint repositories. |
| 52 | + |
| 53 | +Once the repository is created, use the breadcrumbs (upper left) to navigate |
| 54 | +back to the Repositories view. |
| 55 | + |
| 56 | +## Creating a Blueprint from scratch |
| 57 | + |
| 58 | +Now that we have our repositories registered, we are ready to create our first |
| 59 | +blueprint using the UI. |
| 60 | + |
| 61 | +- Click on `Blueprints` tab to see the blueprint repositories. Select a blueprint |
| 62 | +repo where you want to add new blueprint by clicking on it. |
| 63 | +- Clicking on it will take you to a new screen where you can see the packages/blueprints |
| 64 | +that exist in the selected repository. If this is a new repo, list will be empty. |
| 65 | +- Click on `Add Blueprint` button in the upper right corner to create a new blueprint. |
| 66 | +- In `Add Blueprint` interface, complete the setup by entering required information. |
| 67 | +Figure below shows a screenshot of `Add Blueprint` interface. |
| 68 | + |
| 69 | +- After completing the above flow, you’ll be taken to your newly created blueprint |
| 70 | +(see screenshot below). Here you will have a chance to add, edit, and remove |
| 71 | +resources and functions. |
| 72 | + |
| 73 | +- Clicking on any of the resources on the table (currently the `Kptfile` and `ConfigMap`) |
| 74 | +will show the resource viewer dialog where you can see quick information for each |
| 75 | +resource, and optionally view the yaml for the resource. |
| 76 | +- On the blueprint (see screenshot in Step 5), click ‘Edit’ to be able to edit the |
| 77 | +blueprint. After clicking Edit, you should see this screen where you have an option |
| 78 | +to add new resources. |
| 79 | + |
| 80 | +- Using the ‘Add Resource’ button, add a new Namespace resource. Name the |
| 81 | +namespace `example`. |
| 82 | +- Click on Kptfile resource, add a new mutator |
| 83 | + - Search for ‘namespace’ and select ‘set-namespace’ with the latest version |
| 84 | + available for selection. |
| 85 | + - Select ‘kptfile.kpt.dev’ in the config map dropdown |
| 86 | + - By setting both of these values, anytime the blueprint is rendered |
| 87 | + (for instance, on save or when a deployable instance of the blueprint is created), |
| 88 | + the namespace will be set to the name of the package. |
| 89 | +- Using the ‘Add Resource’ button, add a new Role Binding resource |
| 90 | + - Name the resource ‘app-admin’ |
| 91 | + - In Role Reference, select ‘cluster role’ and set ‘app-admin’ as the name |
| 92 | + - Click Add Subject, and in the newly added subject, select ‘Group’ and set the |
| 93 | + |
| 94 | +- Using the ‘Add Resource’ button, add a new Apply Replacements resource. |
| 95 | + - Name the resource ‘update-rolebinding’ |
| 96 | + - Using the yaml view, paste in the following yaml |
| 97 | + |
| 98 | +```yaml |
| 99 | +apiVersion: fn.kpt.dev/v1alpha1 |
| 100 | +kind: ApplyReplacements |
| 101 | +metadata: |
| 102 | + name: update-rolebinding |
| 103 | + annotations: |
| 104 | + config.kubernetes.io/local-config: "true" |
| 105 | +replacements: |
| 106 | +- source: |
| 107 | + kind: ConfigMap |
| 108 | + name: kptfile.kpt.dev |
| 109 | + fieldPath: data.name |
| 110 | + targets: |
| 111 | + - select: |
| 112 | + name: app-admin |
| 113 | + kind: RoleBinding |
| 114 | + fieldPaths: |
| 115 | + - subjects.[kind=Group].name |
| 116 | + options: |
| 117 | + delimiter: '.' |
| 118 | + index: 0 |
| 119 | +``` |
| 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 | +- Click on the Kptfile resource, add a new mutator |
| 125 | + - Search for ‘replacements’ and select `apply-replacements` with the latest |
| 126 | + version available for selection |
| 127 | + - Select the ApplyReplacements update-rolebinding local config object |
| 128 | +- After you are done with the above, you should see the following |
| 129 | + |
| 130 | +- Clicking `Save` will save the resources, apply the mutator, and take you |
| 131 | + back to the blueprint screen you started on. Note that the namespace has |
| 132 | + been updated on the resources from the ‘set-namespace’ mutator. |
| 133 | + |
| 134 | +- Click on the individual resources to see the first class editors. |
| 135 | +- Click Propose to propose the blueprint (button will change to Approve) |
| 136 | +- Click Approve to approve the blueprint |
| 137 | +- Using the breadcrumbs, click back to view your blueprints repository - here |
| 138 | + you should see the blueprint you just created has been finalized. |
| 139 | + |
| 140 | + |
| 141 | +So, with that, we created a blueprint from scratch and published it in blueprint |
| 142 | +repo. You should be able to see the blueprint in the `git` repo as well. |
| 143 | + |
| 144 | +## Create deployable instance of a blueprint |
| 145 | + |
| 146 | +in this section, we will walk through the steps of creating a deployable instance |
| 147 | +of a blueprint. |
| 148 | + |
| 149 | +- Assuming you are on the repository screen, click on `Deployments` tab to list |
| 150 | +deployment repositories (as shown below). Select a deployment repository by |
| 151 | +clicking on it. |
| 152 | + |
| 153 | +- Here is the view for listing all deployments in the deployment repo. |
| 154 | + |
| 155 | +- Click on the `Upstream Repository` link to navigate to the blueprints |
| 156 | + repository and here you should see `basens` blueprint. |
| 157 | + |
| 158 | +- Click on the `basens` blueprint. |
| 159 | + |
| 160 | +- Click the ‘Deploy’ button in the upper right corner to take you to the |
| 161 | + `Add Deployment` flow. Create the new deployment with the name ‘backend’. |
| 162 | + |
| 163 | +- Complete the flow and the package will be added to your deployments |
| 164 | + repository. Note that the namespace across all the resources has been updated |
| 165 | + to the name of the package. |
| 166 | + |
| 167 | +- Using the breadcrumbs, click back the deployments view to see your new |
| 168 | + deployment is added in Draft status. |
| 169 | + |
| 170 | +- Click into the backend deployment and move the deployment to Proposed then |
| 171 | + Published by approving the deployment. |
| 172 | + Optionally, before moving the deployment to Published If you wish too, |
| 173 | + you can make changes to the deployment by adding/removing/updating resources. |
| 174 | + |
| 175 | +- Once the deployment is published, click `Create Sync` to have the `Config Sync` |
| 176 | + sync the deployment to the kubernetes cluster. After a few seconds, you’ll see |
| 177 | + a Sync status update in the upper right hand corner. |
| 178 | + |
| 179 | +- If you navigate back to the `deployment` repo, you will see `sync` status next |
| 180 | + to each deployement 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 package orchestraction UI. |
0 commit comments