pkgdocs

Documentation

Overview

Code generated by "mdtogo"; DO NOT EDIT.

Index

• Variables

Variables

var DescExamples = `` /* 176-byte string literal not displayed */

var DescLong = `
<link rel="stylesheet" type="text/css" href="/kpt/gifs/asciinema-player.css" />
<asciinema-player src="/kpt/gifs/pkg-desc.cast" speed="1" theme="solarized-dark" cols="100" rows="26" font-size="medium" idle-time-limit="1"></asciinema-player>
<script src="/kpt/gifs/asciinema-player.js"></script>

` + "`" + `desc` + "`" + ` reads package information in given DIRs and displays it in tabular format.
Input can be a list of package directories (defaults to the current directory if not specifed).
Any directory with a Kptfile is considered to be a package.

    kpt pkg desc [DIR]...
`

var DescShort = `Print the package origin`

var DiffExamples = `` /* 730-byte string literal not displayed */

var DiffLong = `` /* 2111-byte string literal not displayed */

var DiffShort = `Diff a local package against upstream`

var GetExamples = `` /* 715-byte string literal not displayed */

var GetLong = `` /* 1505-byte string literal not displayed */

var GetShort = `Fetch a package from a git repo`

var InitExamples = `` /* 209-byte string literal not displayed */

var InitLong = `` /* 980-byte string literal not displayed */

var InitShort = `Initialize an empty package`

var READMEExamples = `` /* 1122-byte string literal not displayed */

var READMELong = `
Packages are collections of resource configuration files stored in git repositories.
They may be an entire repo, or a subdirectory within a repo.

| Command  | Description                             |
|----------|-----------------------------------------|
| [desc]   | print the package origin                |
| [diff]   | diff a local package against upstream   |
| [get]    | fetch a package from a git repo         |
| [init]   | initialize an empty package             |
| [sync]   | fetch and update packages declaratively |
| [update] | apply upstream package updates          |

**Data Flow**: git repo -> kpt [pkg] -> local files or stdout

| Configuration Read From | Configuration Written To |
|-------------------------|--------------------------|
| git repository          | local files              |

#### Package Format

1. **Any git repository containing resource configuration files may be used as a package**, no
   additional structure or formatting is necessary.
2. **Any package may be applied with ` + "`" + `kubectl apply -R -f` + "`" + `**.
3. Packages **may be customized in place either manually (e.g. with ` + "`" + `vi` + "`" + `) or programmatically**.
4. Packages **must** be worked on within a local git repo.

![day1 workflow][day1workflow]
![dayN workflow][dayNworkflow]

#### Example imperative package workflow

1. [kpt pkg get](get.md) to get a package
2. [kpt cfg set](../cfg/set.md), [kpt fn run](../fn/run.md) or ` + "`" + `vi` + "`" + ` to modify configuration
3. ` + "`" + `git add` + "`" + ` && ` + "`" + `git commit` + "`" + `
4. ` + "`" + `kubectl apply` + "`" + ` to a cluster:
5. [kpt pkg update](update.md) to pull in new changes
6. ` + "`" + `kubectl apply` + "`" + ` to a cluster

#### Example declarative package workflow

1. [kpt pkg init](init.md)
2. [kpt pkg sync set](sync-set.md) dev version of a package
3. [kpt pkg sync set](sync-set.md) prod version of a package
4. ` + "`" + `git add` + "`" + ` && ` + "`" + `git commit` + "`" + `
5. ` + "`" + `kubectl apply --context dev` + "`" + ` apply to dev
6. ` + "`" + `kubectl apply --context prod` + "`" + ` apply to prod

#### Model

1. **Packages are simply subdirectories of resource configuration files in git**
    * They may also contain supplemental non-resource artifacts, such as markdown files, templates, etc.
    * The ability to fetch a subdirectory of a git repo is a key difference compared to 
      [git subtree](https://github.com/git/git/blob/master/contrib/subtree/git-subtree.txt).

2. **Any existing git subdirectory containing resource configuration files may be used as a package**
    * Nothing besides a git directory containing resource configuration is required.
    * e.g. any [example in the examples repo](https://github.com/kubernetes/examples/staging/cockroachdb) may
      be used as a package:

          kpt pkg get https://github.com/kubernetes/examples/staging/cockroachdb \
            my-cockroachdb
          kubectl apply -R -f my-cockroachdb

3. **Packages should use git references for versioning**.
    * We recommend package authors use semantic versioning when publishing packages for others to consume.

          kpt pkg get https://github.com/kubernetes/examples/staging/cockroachdb@VERSION \
            my-cockroachdb
          kubectl apply -R -f my-cockroachdb

4. **Packages may be modified or customized in place**.
    * It is possible to directly modify the fetched package and merge upstream updates.

5. **The same package may be fetched multiple times** to separate locations.
    * Each instance may be modified and updated independently of the others.

          # fetch an instance of a java package
          kpt pkg get https://github.com/kubernetes/examples/staging/cockroachdb db1
          # make changes...

          # fetch a second instance of a java package
          kpt pkg get https://github.com/kubernetes/examples/staging/cockroachdb db2
          # make changes...

6. **Packages may pull upstream updates after they have been fetched and modified**.
    * Specify the target version to update to, and an (optional) update strategy for how to apply the
      upstream changes.

          kpt pkg get https://github.com/kubernetes/examples/staging/cockroachdb \
            my-cockroachdb
          # make changes...
          kpt pkg update my-cockroachdb@NEW_VERSION --strategy=resource-merge

7. **Packages must be changed within a git repo**.
    * kpt facilitates configuration reuse. Key to that reuse is git. Git is used
      both as a unit to define the boundary of a git repo, but also as the
      boundary of a local workspace. In this way, any workspace is in itself a
      package. Local customizations of packages (or use of specific versions)
      can be re-published as the new canonical package for other users. kpt
      requires any customization to be committed to git before package updates
      can be reconciled.
`

var READMEShort = `Fetch, update, and sync configuration files using git`

var SyncExamples = `` /* 1068-byte string literal not displayed */

var SyncLong = `
Sync uses a manifest to manage a collection of dependencies.

The manifest declares *all* direct dependencies of a package in a Kptfile.
When ` + "`" + `sync` + "`" + ` is run, it will ensure each dependency has been fetched at the
specified ref.

This is an alternative to managing package dependencies individually using
the ` + "`" + `get` + "`" + ` and ` + "`" + `update` + "`" + ` commands.

| Command  | Description                             |
|----------|-----------------------------------------|
| [set]    | add a sync dependency to a Kptfile      |

#### Run Sync

    kpt pkg sync LOCAL_PKG_DIR [flags]

  LOCAL_PKG_DIR:

    Local package with dependencies to sync.  Directory must exist and contain a Kptfile.

#### Env Vars

  KPT_CACHE_DIR:

    Controls where to cache remote packages during updates.
    Defaults to ~/.kpt/repos/

#### Dependencies

For each dependency in the Kptfile, ` + "`" + `sync` + "`" + ` will ensure that it exists locally with the
matching repo and ref.

Dependencies are specified in the ` + "`" + `Kptfile` + "`" + ` ` + "`" + `dependencies` + "`" + ` field and can be added or updated
with ` + "`" + `kpt pkg sync set` + "`" + `.  e.g.

    kpt pkg sync set https://github.com/GoogleContainerTools/kpt.git/package-examples/helloworld-set \
        hello-world
Note that the [set] command must be run from within the local package directory and the
last argument specifies the local destination directory for the dependency.

Or edit the Kptfile directly:

    apiVersion: kpt.dev/v1alpha1
    kind: Kptfile
    dependencies:
    - name: hello-world
      git:
        repo: "https://github.com/GoogleContainerTools/kpt.git"
        directory: "/package-examples/helloworld-set"
        ref: "master"

Dependencies have following schema:

    name: <local path (relative to the Kptfile) to fetch the dependency to>
    git:
      repo: <git repository>
      directory: <sub-directory under the git repository>
      ref: <git reference -- e.g. tag, branch, commit, etc>
    updateStrategy: <strategy to use when updating the dependency -- see kpt help update for more details>
    ensureNotExists: <remove the dependency, mutually exclusive with git>

Dependencies maybe be updated by updating their ` + "`" + `git.ref` + "`" + ` field and running ` + "`" + `kpt pkg sync` + "`" + `
against the directory.
`

var SyncSetExamples = `` /* 603-byte string literal not displayed */

var SyncSetLong = `
Add a sync dependency to a Kptfile.

While is it possible to directly edit the Kptfile, ` + "`" + `set` + "`" + ` can be used to add or update
Kptfile dependencies.

    kpt pkg set REPO_URI[.git]/PKG_PATH[@VERSION] LOCAL_DEST_DIRECTORY [flags]
    
This command must be run from within the local package directory.

  REPO_URI:

    URI of a git repository containing 1 or more packages as subdirectories.
    In most cases the .git suffix should be specified to delimit the REPO_URI from the PKG_PATH,
    but this is not required for widely recognized repo prefixes.  If get cannot parse the repo
    for the directory and version, then it will print an error asking for '.git' to be specified
    as part of the argument.
    e.g. https://github.com/kubernetes/examples.git
    Specify - to read Resources from stdin and write to a LOCAL_DEST_DIRECTORY.

  PKG_PATH:

    Path to remote subdirectory containing Kubernetes Resource configuration files or directories.
    Defaults to the root directory.
    Uses '/' as the path separator (regardless of OS).
    e.g. staging/cockroachdb

  VERSION:

    A git tag, branch, ref or commit for the remote version of the package to fetch.
    Defaults to the repository master branch.
    e.g. @master

  LOCAL_DEST_DIRECTORY:

    The local directory to write the package to.
    e.g. ./my-cockroachdb-copy

    * If the directory does NOT exist: create the specified directory and write
      the package contents to it
    * If the directory DOES exist: create a NEW directory under the specified one,
      defaulting the name to the Base of REPO/PKG_PATH
    * If the directory DOES exist and already contains a directory with the same name
      of the one that would be created: fail

  --strategy:

    Controls how changes to the local package are handled.  Defaults to fast-forward.

    * resource-merge: perform a structural comparison of the original / updated Resources, and merge
	  the changes into the local package.  See ` + "`" + `kpt help apis merge3` + "`" + ` for details on merge.
    * fast-forward: fail without updating if the local package was modified since it was fetched.
    * alpha-git-patch: use 'git format-patch' and 'git am' to apply a patch of the
      changes between the source version and destination version.
      **REQUIRES THE LOCAL PACKAGE TO HAVE BEEN COMMITTED TO A LOCAL GIT REPO.**
    * force-delete-replace: THIS WILL WIPE ALL LOCAL CHANGES TO
      THE PACKAGE.  DELETE the local package at local_pkg_dir/ and replace it
      with the remote version.
`

var SyncSetShort = `Add a sync dependency to a Kptfile`

var SyncShort = `Fetch and update packages declaratively`

var UpdateExamples = `` /* 459-byte string literal not displayed */

var UpdateLong = `
    kpt pkg update LOCAL_PKG_DIR[@VERSION] [flags]


  **Note:** all changes must be committed to git before running update

  LOCAL_PKG_DIR:

    Local package to update.  Directory must exist and contain a Kptfile to be updated.

  VERSION:

  	A git tag, branch, ref or commit.  Specified after the local_package with @ -- pkg@version.
    Defaults the local package version that was last fetched.

	Version types:

    * branch: update the local contents to the tip of the remote branch
    * tag: update the local contents to the remote tag
    * commit: update the local contents to the remote commit

  --strategy:

    Controls how changes to the local package are handled.  Defaults to fast-forward.

    * resource-merge: perform a structural comparison of the original / updated Resources, and merge
	  the changes into the local package.  See ` + "`" + `kpt help apis merge3` + "`" + ` for details on merge.
    * fast-forward: fail without updating if the local package was modified since it was fetched.
    * alpha-git-patch: use 'git format-patch' and 'git am' to apply a patch of the
      changes between the source version and destination version.
      **REQUIRES THE LOCAL PACKAGE TO HAVE BEEN COMMITTED TO A LOCAL GIT REPO.**
    * force-delete-replace: THIS WILL WIPE ALL LOCAL CHANGES TO
      THE PACKAGE.  DELETE the local package at local_pkg_dir/ and replace it
      with the remote version.

  -r, --repo string

    Git repo url for updating contents.  Defaults to the repo the package was fetched from.

  --dry-run

    Print the 'alpha-git-patch' strategy patch rather than merging it.

#### Env Vars

  KPT_CACHE_DIR:

    Controls where to cache remote packages when fetching them to update local packages.
    Defaults to ~/.kpt/repos/
`

var UpdateShort = `Apply upstream package updates`