github.com/Racer159/jackal@v0.32.7-0.20240401174413-0bd2339e4f2e/docs/5-jackal-tutorials/7-publish-and-deploy.md (about)

     1  # Publish & Deploy Packages w/OCI
     2  
     3  ## Introduction
     4  
     5  In this tutorial, we are going to run through how to publish a Jackal package to an [OCI](https://github.com/opencontainers/image-spec) compliant registry, allowing end users to pull and deploy packages without needing to build locally, or transfer the package to their environment.
     6  
     7  ## System Requirements
     8  
     9  - Internet access to download resources or upload packages
    10  - Access to a registry (this tutorial uses Docker Hub)
    11  
    12  ## Prerequisites
    13  
    14  For following along locally, please ensure the following prerequisites are met:
    15  
    16  - Jackal binary installed on your `$PATH`: ([Installing Jackal](../1-getting-started/index.md#installing-jackal))
    17  - Access to a [Registry supporting the OCI Distribution Spec](https://oras.land/implementors/#registries-supporting-oci-artifacts), this tutorial will be using Docker Hub
    18  - Access to a cluster that has been [initialized with jackal](./1-initializing-a-k8s-cluster.md).
    19  
    20  ## Youtube Tutorial
    21  [![Using OCI to Store & Deploy Jackal Packages Video on YouTube](../.images/tutorials/publish_and_deploy_thumbnail.png)](https://www.youtube.com/watch?v=QKxgJnC_37Y "Using OCI to Store & Deploy Jackal Packages")
    22  
    23  ## Working with OCI Packages
    24  
    25  This tutorial will require a registry to be configured (see [prerequisites](#prerequisites) for more information).  The below sets up some variables for us to use when logging into the registry:
    26  
    27  <iframe src="/docs/tutorials/publish_and_deploy_setup.html" height="130px" width="100%"></iframe>
    28  
    29  With those set, you can tell Jackal to login to your registry with the following:
    30  
    31  <iframe src="/docs/tutorials/publish_and_deploy_login.html" width="100%" height="80px"></iframe>
    32  
    33  :::note
    34  
    35  If you do not have the Docker CLI installed, you may need to create a Docker compliant auth config file manually:
    36  
    37  <iframe src="/docs/tutorials/publish_and_deploy_docker_config.html" width="100%" height="225px"></iframe>
    38  
    39  :::
    40  
    41  ### Publish Package
    42  
    43  First, create a valid Jackal package definition (`jackal.yaml`), with the `metadata.version` key set.
    44  
    45  <iframe src="/docs/tutorials/publish_and_deploy_manifest.html" width="100%" height="400px"></iframe>
    46  
    47  
    48  Create the package locally:
    49  
    50  [CLI Reference](../2-the-jackal-cli/100-cli-commands/jackal_package_create.md)
    51  
    52  <iframe src="/docs/tutorials/publish_and_deploy_create.html" width="100%" height="600px"></iframe>
    53  
    54  Then publish the package to the registry:
    55  
    56  :::note
    57  
    58  Your package tarball may be named differently based on your machine's architecture.  For example, if you are running on an AMD64 machine, the tarball will be named `jackal-package-helm-oci-chart-amd64-0.0.1.tar.zst`.
    59  
    60  :::
    61  
    62  [CLI Reference](../2-the-jackal-cli/100-cli-commands/jackal_package_publish.md)
    63  
    64  <iframe src="/docs/tutorials/publish_and_deploy_publish.html" width="100%" height="700px"></iframe>
    65  
    66  :::note
    67  
    68  The name and reference of this OCI artifact is derived from the package metadata, e.g.: `helm-oci-chart:0.0.1-arm64`
    69  
    70  To modify, edit `jackal.yaml` and re-run `jackal package create .`
    71  
    72  :::
    73  
    74  :::info
    75  
    76  The above publish command publishes a fully-built package that is ready to deploy to a cluster, but this isn't the only kind of package you can publish to an OCI registry.
    77  
    78  If you specify a path to a directory containing a `jackal.yaml` (as you would on `jackal package create`) you can create a `skeleton` package that is importable into other packages using [component composability](../../examples/composable-packages/README.md).  These can be inspected like normal Jackal packages but cannot be deployed as they haven't been fully created yet.
    79  
    80  :::
    81  
    82  ### Inspect Package
    83  
    84  [CLI Reference](../2-the-jackal-cli/100-cli-commands/jackal_package_inspect.md)
    85  
    86  Inspecting a Jackal package stored in an OCI registry is the same as inspecting a local package and has the same flags:
    87  
    88  <iframe src="/docs/tutorials/publish_and_deploy_inspect.html" width="100%" height="520px"></iframe>
    89  
    90  
    91  ### Deploy Package
    92  
    93  [CLI Reference](../2-the-jackal-cli/100-cli-commands/jackal_package_deploy.md)
    94  
    95  Deploying a package stored in an OCI registry is nearly the same experience as deploying a local package:
    96  
    97  <iframe src="/docs/tutorials/publish_and_deploy_deploy.html" width="100%" height="800px"></iframe>
    98  
    99  ### Pull Package
   100  
   101  [CLI Reference](../2-the-jackal-cli/100-cli-commands/jackal_package_pull.md)
   102  
   103  Packages can be saved to the local disk in order to deploy a package multiple times without needing to fetch it every time.
   104  
   105  <iframe src="/docs/tutorials/publish_and_deploy_pull.html" width="100%" height="450px"></iframe>
   106  
   107  
   108  ## Removal
   109  
   110  1. Use the `jackal package list` command to get a list of the installed packages.  This will give you the name of the games package to remove it.
   111  
   112  <iframe src="/docs/tutorials/publish_and_deploy_list.html" width="100%"></iframe>
   113  
   114  2. Use the `jackal package remove` command to remove the `helm-oci-chart` package.  Don't forget the `--confirm` flag.  Otherwise you'll receive an error.
   115  
   116  <iframe src="/docs/tutorials/publish_and_deploy_remove.html" width="100%" height="115px"></iframe>
   117  
   118  ## Troubleshooting
   119  
   120  ### Failed to publish package: version is required for publishing
   121  
   122  <iframe src="/docs/tutorials/troubleshoot_version_required_publish.html" width="100%" height="130px"></iframe>
   123  
   124  :::info Remediation
   125  
   126  You attempted to publish a package with no version metadata.
   127  
   128  <iframe src="/docs/tutorials/troubleshoot_version_required_no_version.html" width="100%" height="300px"></iframe>
   129  
   130  1. Open the jackal.yaml file.
   131  2. Add a version attribute to the [package metadata](https://docs.jackal.dev/docs/user-guide/jackal-schema#metadata)
   132  3. Recreate the package with the `jackal package create` command.
   133  4. Publish the package.  The filename will now have the version as part of it.
   134  
   135  :::
   136  
   137  ### Failed to publish, http: server gave HTTP response to HTTPS client
   138  
   139  <iframe src="/docs/tutorials/troubleshoot_insecure_registry.html" width="100%" height="375px"></iframe>
   140  
   141  :::info Remediation
   142  
   143  You attempted to publish a package to an insecure registry, using http instead of https.
   144  
   145  1. Use the `--insecure` flag.  Note that this is not suitable for production workloads.
   146  
   147  :::
   148  
   149  ### Unable to connect to the Kubernetes cluster.
   150  
   151  <iframe src="/docs/tutorials/troubleshoot_unreachable.html" width="100%" height="200px"></iframe>
   152  
   153  :::info Remediation
   154  
   155  If you receive this error, either you don't have a Kubernetes cluster, your cluster is down, or your cluster is unreachable.
   156  
   157  1. Check your kubectl configuration, then try again.  For more information about kubectl configuration see [Configure Access to Multiple Clusters](https://kubernetes.io/docs/tasks/access-application-cluster/configure-access-multiple-clusters/) from the Kubernetes documentation.
   158  
   159  If you need to setup a cluster, you can perform the following.
   160  
   161  1. Deploy a Kubernetes cluster with the [Creating a K8s Cluster with Jackal](./5-creating-a-k8s-cluster-with-jackal.md) tutorial.
   162  2. Perform the [Initialize a cluster](./1-initializing-a-k8s-cluster.md) tutorial.
   163  
   164  After that you can try deploying the package again.
   165  
   166  :::
   167  
   168  ### Secrets "jackal-state" not found.
   169  
   170  <iframe src="/docs/tutorials/troubleshoot_uninitialized.html" width="100%" height="250px"></iframe>
   171  
   172  :::info Remediation
   173  
   174  If you receive this error when jackal is attempting to deploy any component, this means you have not initialized the kubernetes cluster.  This is one of the prerequisites for this tutorial.  Perform the [Initialize a cluster](./1-initializing-a-k8s-cluster.md) tutorial, then try again.
   175  
   176  :::