github.com/SamarSidharth/kpt@v0.0.0-20231122062228-c7d747ae3ace/site/guides/namespace-provisioning-ui.md (about)

     1  # Namespace provisioning using UI
     2  
     3  This guide will teach us how to create a kpt package from scratch using Config
     4  as Data UI. We will also learn how to enable customization of the package with
     5  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** link on the Team Blueprints card
    35  to register a blueprint repository. Enter the following details in the Register
    36  Repository flow:
    37  
    38  - In the Repository Details section, the Repository URL is the clone URL from
    39    your repository. Branch and directory can be left blank. Branch will default
    40    to "main" and directory will default to "/".
    41  - In the Repository Authentication section, you will need to use the GitHub
    42    Personal Access Token (unless your repository allows for unauthenticated
    43    writes). GitHub Personal Access Tokens can be created at
    44    <https://github.com/settings/tokens>, and must include the 'repo' scope.
    45  - In the Repository Content section, select "Team Blueprints".
    46  
    47  Once the repository is registered, use the breadcrumbs (upper left) to navigate
    48  to the **Package Management** screen.
    49  
    50  ### Registering deployment repository
    51  
    52  Start by clicking the **Register Repository** link on the Deployments card to
    53  register a deployment repository. Enter the following details in the Register
    54  Repository flow:
    55  
    56  - In the Repository Details section, the Repository URL is the clone URL from
    57    your repository. Branch and Directory can be left blank. Branch will default
    58    to "main", and directory will default to "/".
    59  - In the Repository Authentication section, either create a new secret, or
    60    optionally select the same secret in the Authentication Secret dropdown you
    61    created for registering the blueprint repository.
    62  - In the Repository Content section, select "Deployments".
    63  
    64  Once the repository is created, use the breadcrumbs (upper left) to navigate to
    65  the **Package Management** screen.
    66  
    67  ## Creating a Blueprint from scratch
    68  
    69  Now that we have our repositories registered, we are ready to create the simple
    70  namespace team blueprint using the UI.
    71  
    72  - From the **Package Management** screen, click the **Team Blueprints →** link.
    73  - Clicking the link will take you to a Team Blueprints screen where you can view
    74    and add team blueprints.
    75  - Click the **ADD TEAM BLUEPRINT** button in the upper right corner to create a
    76    new team blueprint.
    77  - On the Add Team Blueprint screen:
    78    - Choose "Create a new team blueprint from scratch".
    79    - Click Next to proceed to the Metadata section.
    80    - Set the team blueprint name to "simplens".
    81    - Click Next to proceed to the Namespace section.
    82    - Check the "Add namespace resource to the team blueprint" checkbox. Checking
    83      this checkbox will automatically add a Namespace resource to the team
    84      blueprint.
    85    - Set namespace option to "Set the namespace to the name of the deployment
    86      instance". This option will set the name of the namespace equal to the name
    87      of the deployment package when a deployment package is created/cloned from
    88      this team blueprint by adding the set-namespace mutator to the Kptfile
    89      resource. Since we are creating a team blueprint, the namespace will be set
    90      to "example".
    91    - Click Next to proceed to the Validate Resources section.
    92    - Click Next to proceed to the Confirm section.
    93    - Click the **CREATE TEAM BLUEPRINT** button.
    94  - The next screen is the package editor screen for the new _Draft_ team
    95    blueprint package you have just created. Here we will want to add a few
    96    resources to complete the team blueprint.
    97    - Click the **EDIT** button to allow the team blueprint to be updated.
    98    - Click the **ADD BUTTON** button and add a new Role Binding resource.
    99      - In the Resource Metadata section, name the resource "app-admin".
   100      - In Role Reference section, set the kind to "Cluster Role" and name to
   101        "app-admin" .
   102      - Click the **ADD SUBJECT** button, and in the newly added subject section,
   103        set the kind to "Group" and name to "example.admin@bigco.com".
   104      - Click the **SAVE** button to close the add resource dialog.
   105    - Click the **ADD BUTTON** button and add a new Apply Replacements resource.
   106      - In the Resource Metadata section, name the resource "update-rolebinding"
   107      - In the Source section, set the source resource as "ConfigMap:
   108        kptfile.kpt.dev" and source path to "data.name: example"
   109      - In the Target section, set the target resource to "RoleBinding:
   110        app-admin", the target path to "subjects.0.name: example.admin@bigco.com".
   111        Set the replacement value option to "Partial value", delimiter to "period
   112        (.)", and replace to "example".
   113      - Click the **SAVE** button to close the add resource dialog.
   114    - Click the **ADD BUTTON** button and add a new Resource Quota resource.
   115      - In the Resource Metadata section, name the resource "base".
   116      - In the Compute Resources setion, set Max CPU Requests to "40" and Max
   117        Memory Requests to "40G".
   118      - Click the **SAVE** button to close the add resource dialog.
   119    - Click the **SAVE** button on the upper right corner of the screen.
   120  - This will bring you back to the team blueprint screen. The team blueprint is
   121    still in _Draft_ status so we will need to publish it to make it available for
   122    deployment.
   123    - Click the **PROPOSE** button to propose the simplens team blueprint package
   124      for review.
   125    - It will change to **APPROVE** momentarily. Click that button to publish the
   126      simplens team blueprint.
   127  - Using the breadcrumbs, click back to view your blueprints repository - here
   128    you should see the blueprint you just created has been published.
   129  
   130  This completes the simplens team blueprint. The next section shows how
   131  deployable instances can be created using this team blueprint.
   132  
   133  ## Create a deployable instance of the team blueprint
   134  
   135  In this section, we will walk through creating a deployable instance of the
   136  simplens team blueprint.
   137  
   138  - From the **Package Management** screen, click the **Team Blueprints →** link.
   139  - Here you should see the "simplens" team blueprint created in the section
   140    above.
   141  - Click the "simplens" team blueprint row to view the blueprint.
   142  - Click the **CLONE** button.
   143  - In the **Clone simplens** screen:
   144    - Choose "Create a new deployment by cloning the simplens team blueprint"
   145      option.
   146    - Click Next to proceed to the Metadata section.
   147    - Update the deployment name to "backend".
   148    - Click Next to proceed to the Namespace section.
   149    - Click Next to proceed to the Validate Resources section.
   150    - Click Next to proceed to the Confirm section.
   151    - Click the **CREATE DEPLOYMENT** button.
   152  - The next screen is the package editor screen for the new _Draft_ deployment
   153    package you have just created. Note that the namespace across all the
   154    namespace scoped resources has been updated to the name of the package.
   155    - Click the **DIFF** button for any resource to view the differences between
   156      the resource and the same resource in the upstream simplens team blueprint.
   157      For many of the deployable resources, only the namespace will be updated.
   158      For the app-admin RoleBiding resource, the group binding has also been
   159      updated by the Apply Replacements resource.
   160  - We need to publish the deployment package to make it available for deployment.
   161    - Before moving the deployment to _Proposed_, you can make changes by editing
   162      the deployment and adding, removing, and updating resources.
   163    - Click the **PROPOSE** button to propose the backend deployment package for
   164      review.
   165    - It will change to **APPROVE** momentarily. Click that button to publish the
   166      backend deployment package.
   167  - Once the deployment package is published, click the **CREATE SYNC** button to
   168    have _Config Sync_ sync the deployment to the Kubernetes cluster.
   169    - After a few seconds, you will see the Sync status update in the upper
   170      right-hand corner.
   171  - Navigating back to the deployment repository the _SYNC STATUS_ column shows
   172    the status of each deployment package.
   173  
   174  This completes our end-to-end workflow of creating a blueprint from scratch and
   175  deploying a variant of the blueprint to a Kubernetes cluster using the Config as
   176  Data UI.