github.com/wmuizelaar/kpt@v0.0.0-20221018115725-bd564717b2ed/package-examples/kustomize/README.md (about)

     1  # kustomize
     2  
     3  ## Overview
     4  
     5  This example demonstrates using kpt and kustomize together. Specifically it
     6  uses:
     7  
     8  - kpt for packaging (`kpt pkg`)
     9  - kpt for actuation (`kpt live`)
    10  - kustomize for customization (`kustomize build`)
    11  
    12  ## Steps
    13  
    14  Fetch this package:
    15  
    16  ```shell
    17  $ kpt pkg get https://github.com/GoogleContainerTools/kpt.git/package-examples/kustomize
    18  ```
    19  
    20  You can view the package hierarchy using the `kpt pkg tree` command or a regular
    21  `tree` command:
    22  
    23  ```shell
    24  $ tree kustomize
    25  
    26  kustomize
    27  ├── Kptfile
    28  ├── README.md
    29  ├── bases
    30  │   └── nginx
    31  │       ├── Kptfile
    32  │       ├── deployment.yaml
    33  │       ├── kustomization.yaml
    34  │       └── svc.yaml
    35  └── overlays
    36      ├── dev
    37      │   ├── Kptfile
    38      │   ├── kustomization.yaml
    39      │   └── pass-patch.yaml
    40      └── prod
    41          ├── Kptfile
    42          ├── kustomization.yaml
    43          └── pass-patch.yaml
    44  ```
    45  
    46  The package hierarchy contains several packages which can be classified into
    47  three categories:
    48  
    49  1. `kustomize` is the top-level package.
    50  2. `bases/nginx` this package serves as a local base.
    51  3. `overlays/dev` and `overlays/prod` are overlays which have patches for the
    52     `nginx` base package.
    53  
    54  Having a local base that is a kpt package has several advantages over remote
    55  bases:
    56  
    57  1. Consumers of the remote base are able to pull in updates only when they are
    58     ready to update avoiding surprises.
    59  2. Consumer can do in place edits like adding a file or editing a file without
    60     having to create a patch for everything.
    61  
    62  Note that we have added a `kustomization.yaml` in the `base/nginx` for the
    63  `kustomize build` to be able to get all the resources files. The overlays have
    64  their own kustomization instructions which allow per environment changes.
    65  
    66  In order to see what the final configuration looks like you can use use the
    67  familiar `kustomize build`:
    68  
    69  ```shell
    70  $ kustomize build kustomize/overlays/dev
    71  apiVersion: v1
    72  kind: Service
    73  metadata:
    74    labels:
    75      app: nginx
    76      environ: dev
    77    name: dev-my-nginx-svc
    78  spec:
    79    ports:
    80    - port: 80
    81    selector:
    82      app: nginx
    83      environ: dev
    84    type: LoadBalancer
    85  ---
    86  apiVersion: apps/v1
    87  kind: Deployment
    88  metadata:
    89    labels:
    90      environ: dev
    91    name: dev-my-nginx
    92  spec:
    93    replicas: 1
    94    selector:
    95      matchLabels:
    96        app: nginx
    97        environ: dev
    98    template:
    99      metadata:
   100        labels:
   101          app: nginx
   102          environ: dev
   103      spec:
   104        containers:
   105        - image: nginx:1.14.1
   106          name: nginx
   107          ports:
   108          - containerPort: 80
   109  ---
   110  apiVersion: kpt.dev/v1
   111  info:
   112    description: sample description
   113  kind: Kptfile
   114  metadata:
   115    labels:
   116      environ: dev
   117    name: dev-dev
   118  ```
   119  
   120  This rendered configuration can be deployed with `kubectl` but you can also take
   121  advantage of `kpt live apply` if you extend your kustomization.yaml to include
   122  the Kptfile. You can learn more about kpt `apply` command in the [deployment
   123  chapter].
   124  
   125  In our case we created Kptfiles in the overlay folders and added the Kptfile to
   126  the list of kustomize resources `kustomize/overlays/dev/kustomization.yaml`:
   127  
   128  ```yaml
   129  apiVersion: kustomize.config.k8s.io/v1beta1
   130  kind: Kustomization
   131  resources:
   132    - ../../bases/nginx
   133    - Kptfile
   134  patches:
   135    - path: pass-patch.yaml
   136      target:
   137        kind: Deployment
   138  commonLabels:
   139    environ: dev
   140  namePrefix: dev-
   141  ```
   142  
   143  In this solution the overlays are targeting different environments, they can be
   144  on different clusters or in different namespaces. In order to take advantage of
   145  kpt live apply the final `kustomize build` needs to contain the inventory
   146  object.
   147  
   148  ```shell
   149  $ kpt live init kustomize/overlays/dev
   150  initializing Kptfile inventory info (namespace: default)...success
   151  ```
   152  
   153  You can then pipe the kustomize build to kpt:
   154  
   155  ```shell
   156  $ kustomize build kustomize/overlays/dev | kpt live apply -
   157  
   158  service/dev-my-nginx-svc created
   159  deployment.apps/dev-my-nginx created
   160  2 resource(s) applied. 2 created, 0 unchanged, 0 configured, 0 failed
   161  0 resource(s) pruned, 0 skipped, 0 failed
   162  ```
   163  
   164  You could also consider changing your hydration logic to `kpt fn render` with an
   165  out of place hydration flag, but that would require a manual migration which is
   166  out of scope for this solution. More about the kpt functions and the pipeline
   167  can be found in the [using functions] chapter of The Kpt Book.
   168  
   169  [deployment chapter]: https://kpt.dev/book/06-deploying-packages/
   170  [using functions]: https://kpt.dev/book/04-using-functions/