github.com/wmuizelaar/kpt@v0.0.0-20221018115725-bd564717b2ed/site/book/03-packages/01-getting-a-package.md (about)

     1  Packaging in kpt is based on Git forking. Producers publish packages by
     2  committing them to a Git repository. Consumers fork the package to use it.
     3  
     4  Let's revisit the Wordpress example:
     5  
     6  ```shell
     7  $ kpt pkg get https://github.com/GoogleContainerTools/kpt.git/package-examples/wordpress@v0.9
     8  ```
     9  
    10  A package in a Git repo can be fetched by specifying a branch, tag, or commit
    11  SHA. In this case, we are specifying tag `v0.9`.
    12  
    13  ?> Refer to the [get command reference][get-doc] for usage.
    14  
    15  The `Kptfile` contains metadata about the origin of the forked package. Take a
    16  look at the content of the `Kptfile` on your local filesystem:
    17  
    18  ```yaml
    19  # wordpress/Kptfile
    20  apiVersion: kpt.dev/v1
    21  kind: Kptfile
    22  metadata:
    23    name: wordpress
    24  upstream:
    25    type: git
    26    git:
    27      repo: https://github.com/GoogleContainerTools/kpt
    28      directory: /package-examples/wordpress
    29      ref: v0.9
    30    updateStrategy: resource-merge
    31  upstreamLock:
    32    type: git
    33    git:
    34      repo: https://github.com/GoogleContainerTools/kpt
    35      directory: /package-examples/wordpress
    36      ref: package-examples/wordpress/v0.9
    37      commit: b9ea0bca019dafa9f9f91fd428385597c708518c
    38  info:
    39    emails:
    40      - kpt-team@google.com
    41    description: This is an example wordpress package with mysql subpackage.
    42  pipeline:
    43    mutators:
    44      - image: gcr.io/kpt-fn/set-labels:v0.1
    45        configMap:
    46          app: wordpress
    47    validators:
    48      - image: gcr.io/kpt-fn/kubeval:v0.3
    49  ```
    50  
    51  The `Kptfile` contains two sections to keep track of the upstream package:
    52  
    53  1. The `upstream` section contains the user-specified Git reference to the
    54     upstream package. This contains three pieces of information:
    55     - `repo`: The Git repository where the package can be found
    56     - `directory`: The directory within the Git repository where this package can
    57       be found
    58     - `ref`: The Git reference for the package. This can be either a branch, tag,
    59       or commit SHA.
    60  2. The `upstreamLock` section records the upstream Git reference (exact Git SHA)
    61     that was fetched by kpt. This section is managed by kpt and should not be
    62     changed manually.
    63  
    64  Now, let's look at the `Kptfile` for the `mysql` subpackage:
    65  
    66  ```yaml
    67  # wordpress/mysql/Kptfile
    68  apiVersion: kpt.dev/v1
    69  kind: Kptfile
    70  metadata:
    71    name: mysql
    72  info:
    73    emails:
    74      - kpt-team@google.com
    75    description: This is an example mysql package.
    76  pipeline:
    77    mutators:
    78      - image: gcr.io/kpt-fn/set-labels:v0.1
    79        configMap:
    80          tier: mysql
    81  ```
    82  
    83  As you can see, this `Kptfile` doesn't have the `upstream` and `upstreamLock`
    84  sections. This is because there are two different package types in kpt:
    85  
    86  - **Independent package:** A package where the `Kptfile` has `upstream` defined.
    87  - **Dependent package:** A package where the `Kptfile` doesn’t have `upstream`
    88    defined.
    89  
    90  In this case, the `mysql` subpackage is a _dependent package_. The upstream
    91  package for `mysql` is automatically inferred from the parent package. You can
    92  think of the `Kptfile` in the `mysql` package as implicitly inheriting the
    93  `upstream` section of its parent, with the only difference being that
    94  `upstream.directory` in the subpackage would instead point to
    95  `/package-examples/wordpress/mysql`.
    96  
    97  ## Package Name and Identifier
    98  
    99  It is possible to specify a different local directory name to the `get` command.
   100  For example, the following fetches the packages to a directory named
   101  `mywordpress`:
   102  
   103  ```shell
   104  $ kpt pkg get https://github.com/GoogleContainerTools/kpt.git/package-examples/wordpress@v0.9 mywordpress
   105  ```
   106  
   107  The _name of a package_ is given by its directory name. Since the Kptfile is a
   108  KRM resource and follows the familiar structure of KRM resources, the name of
   109  the package is also available from the `metadata.name` field. This must always
   110  be the name of the directory, and kpt will update it automatically when forking
   111  a package. In this case, `metadata.name` is set to `mywordpress`.
   112  
   113  In general, the package name is not unique. The _unique identifier_ for a
   114  package is defined as the relative path from the top package to the subpackage.
   115  For example, we could have two subpackages with the name `mysql` having the
   116  following identifiers:
   117  
   118  - `wordpress/backend/mysql`
   119  - `wordpress/frontend/mysql`
   120  
   121  [get-doc]: /reference/cli/pkg/get/