kcl-lang.io/kpm@v0.8.7-0.20240520061008-9fc4c5efc8c7/docs/kpm_oci.md (about)

     1  # Use OCI-based Registries
     2  
     3  Beginning in kpm v0.2.0, you can use container registries with OCI support to store and share kcl packages.
     4  
     5  ## kpm registry
     6  
     7  kpm supports using OCI registries to store and share kcl packages. kpm uses `ghcr.io` to store kcl packages by default.
     8  
     9  kpm default registry - [https://github.com/orgs/KusionStack/packages](https://github.com/orgs/KusionStack/packages)
    10  
    11  You can adjust the registry url and repo name in the kpm configuration file. The kpm configuration file is located at `$KCL_PKG_PATH/.kpm/config.json`, and if the environment variable `KCL_PKG_PATH` is not set, it is saved by default at `$HOME/.kcl/kpm/.kpm/config.json`.
    12  
    13  The default content of the configuration file is as follows:
    14  
    15  ```json
    16  {
    17      "DefaultOciRegistry":"ghcr.io",
    18      "DefaultOciRepo":"kcl-lang"
    19  }
    20  ```
    21  
    22  ## Quick Start with OCI Registry
    23  
    24  In the following sections, a temporary OCI registry was set up on `localhost:5001` in a local environment, and an account `test` with the password `1234` was added for this OCI registry.
    25  
    26  ### kpm login
    27  
    28  You can use `kpm login` in the following four ways.
    29  
    30  #### 1. login to a registry with account and password
    31  
    32  ```shell
    33  $ kpm login -u <account_name> -p <password> <oci_registry>
    34  Login succeeded
    35  ```
    36  
    37  <img src="./gifs/kpm_login.gif" width="600" align="center" />
    38  
    39  #### 2. login to a registry with account, and enter the password interactively.
    40  
    41  ```shell
    42  $ kpm login -u <account_name> <oci_registry>
    43  Password:
    44  Login succeeded
    45  ```
    46  
    47  <img src="./gifs/kpm_login_with_pwd.gif" width="600" align="center" />
    48  
    49  #### 3. login to a registry, and enter the account and password interactively.
    50  
    51  ```shell
    52  $ kpm login <oci_registry>
    53  Username: <account_name>
    54  Password:
    55  Login succeeded
    56  ```
    57  
    58  <img src="./gifs/kpm_login_with_both.gif" width="600" align="center" />
    59  
    60  ### kpm logout
    61  
    62  You can use `kpm logout` to logout from a registry
    63  
    64  ```shell
    65  kpm logout <registry>
    66  ```
    67  
    68  <img src="./gifs/kpm_logout.gif" width="600" align="center" />
    69  
    70  ### kpm push
    71  
    72  You can use `kpm push` under the kcl package root directory to upload a kcl package to an OCI-based registry.
    73  
    74  ```shell
    75  # create a new kcl package.
    76  $ kpm init <package_name> 
    77  # enter the kcl package root directory
    78  $ cd <package_name> 
    79  # push it to the default oci registry specified in the configuration file 'kpm.json'.
    80  $ kpm push
    81  ```
    82  
    83  <img src="./gifs/kpm_push.gif" width="600" align="center" />
    84  
    85  You can also use `kpm push` to upload a kcl package to an OCI-based registry by specifying the registry url.
    86  
    87  ```shell
    88  # create a new kcl package.
    89  $ kpm init <package_name> 
    90  # enter the kcl package root directory
    91  $ cd <package_name> 
    92  # push it to an oci registry
    93  $ kpm push <oci_url>
    94  ```
    95  
    96  <img src="./gifs/kpm_push_with_url.gif" width="600" align="center" />
    97  
    98  ### kpm pull
    99  
   100  You can use `kpm pull` to download a kcl package from the default OCI registry by kcl package name.
   101  `kpm` will download the kcl package from the default OCI registry specified in the configuration file `kpm.json`.
   102  
   103  ```shell
   104  kpm pull <package_name>:<package_version>
   105  ```
   106  
   107  <img src="./gifs/kpm_pull.gif" width="600" align="center" />
   108  
   109  Or you can download a kcl package from an OCI-based registry url.
   110  
   111  ```shell
   112  kpm pull --tag <kcl_package_version> <oci_url>
   113  ```
   114  
   115  <img src="./gifs/kpm_pull_with_url.gif" width="600" align="center" />
   116  
   117  ### kpm run
   118  
   119  Run an oci url or ref to compile a package in oci registry.
   120  
   121  ```shell
   122  kpm run --tag <kcl_package_version> <oci_url>
   123  ```
   124  
   125  <img src="./gifs/kpm_run_oci_url.gif" width="600" align="center" />
   126  
   127  Alternatively, you can compile a kcl package directly from an oci ref using `kpm run`.
   128  
   129  ```shell
   130  kpm run <oci_ref>
   131  ```
   132  
   133  <img src="./gifs/kpm_run_oci_ref.gif" width="600" align="center" />