github.com/Racer159/jackal@v0.32.7-0.20240401174413-0bd2339e4f2e/docs/0-jackal-overview.md (about) 1 --- 2 sidebar_position: 0 3 --- 4 5 # Overview 6 7  8 9 ## What is Jackal? 10 11 Jackal was created to _**support the declarative creation & distribution of software "packages" into remote/constrained/standalone environments**_. 12 13 > "Jackal is a tool to help deploy modern stacks into air-gapped environments; it's all about moving the bits." — Jeff 14 15 Jackal is a free and open-source tool that simplifies the setup and deployment of applications and supporting resources onto air-gapped or disconnected environments. Jackal equips you with the ability to quickly and securely deploy modern software onto complex systems without relying on internet connectivity. 16 17 It also simplifies the installation, update, and maintenance of supporting DevSecOps capabilities like Kubernetes clusters and logging stacks, while providing features that ensure supply chain security, including SBOM compliance. Most importantly though, Jackal keeps applications and systems running even when they are disconnected. 18 19 :::note 20 21 Check out our [glossary](1-getting-started/1-understand-the-basics.md) for an explanation of common terms used in the project. 22 23 ::: 24 25 ## How Jackal Works 26 27 Jackal simplifies and standardizes the delivery of complex software deployments. This gives users the ability to reduce tens/hundreds of individual software updates, data transfers, and manual installations to a few simple terminal commands. This tool equips users with the ability to pull, package, and install all of the resources their applications or clusters need to run without being connected to the internet. It can also deploy any necessary resources needed to stand up infrastructure tooling (such as Open Tofu / Terraform). 28 29  30 31 A typical Jackal deployment is made up of three parts: 32 33 1. The [`jackal` binary](./2-the-jackal-cli/index.md): 34 - Is a statically compiled Go binary that can be run on any machine, server, or operating system with or without connectivity. 35 - Creates packages combining numerous types of software/updates into a single distributable package (while on a network capable of accessing them). 36 - Declaratively deploys package contents "into place" for use on production systems (while on an isolated network). 37 2. A [Jackal init package](./3-create-a-jackal-package/3-jackal-init-package.md): 38 - A compressed tarball package that contains the configuration needed to instantiate an environment without connectivity. 39 - Automatically seeds your cluster with a container registry or wires up a pre-existing one 40 - Provides additional capabilities such as logging, git server support, and/or a K8s cluster. 41 3. A [Jackal Package](./3-create-a-jackal-package/1-jackal-packages.md): 42 - A compressed tarball package that contains all of the files, manifests, source repositories, and images needed to deploy your infrastructure, application, and resources in a disconnected environment. 43 44 :::note 45 46 For more technical information on how Jackal works and to view the Jackal architecture, visit our [Nerd Notes page](./12-contribute-to-jackal/3-nerd-notes.md). 47 48 ::: 49 50 ## Target Use Cases 51 52 - Make the delivery of software "across the air gap" an open-source "solved problem". 53 - Make it trivial to deploy and run Kubernetes apps "at the Edge". 54 - Make it easy to support GitOps-based K8s cluster updates in isolated environments. 55 - Make it possible to support GitOps-based K8s cluster updates in internet-connected-but-independent environments (think: dependency caching per availability zone, etc). 56 57 ## What can be Packaged? 58 59 The following types of software can be rolled into a Jackal Package: 60 61 - Container images + artifacts: to serve images and OCI artifacts for clusters and other consumers to pull. 62 - [Repositories](../examples/git-data/README.md): to serve as the git-based "source of truth" for GitOps application deployments. 63 - Pre-compiled binaries: to provide the software necessary to start and support a cluster. 64 - [Component actions](3-create-a-jackal-package/7-component-actions.md): to support scripts and commands that run at various stages of the Jackal [package create lifecycle](./3-create-a-jackal-package/5-package-create-lifecycle.md), and [package deploy lifecycle](./4-deploy-a-jackal-package/1-package-deploy-lifecycle.md). 65 - Helm charts, kustomizations, and other K8s manifests: to apply to a Kubernetes cluster. 66 - [Data injections](../examples/kiwix/README.md): to declaratively inject data into running containers in a Kubernetes cluster. 67 68 ## How To Use Jackal 69 70 Jackal is intended for use in a software deployment process that looks similar to this: 71 72  73 74 ### (0) Connect to the Internet 75 76 Jackal doesn't build software—it helps you distribute software that already exists. 77 78 Jackal can pull from various places like Docker Hub, Iron Bank, GitHub, private registries and local filesystems. In order to do this, you must ensure that Jackal has a clear path and appropriate access credentials. Be sure you know what you want to pack and how to access it before you begin using Jackal. 79 80 ### (1) Create a Package 81 82 This part of the process requires access to the internet (or a network that mirrors your resources). When the `jackal` binary is presented with a `jackal.yaml`, it then begins downloading, packing, and compressing the software that you requested. It then outputs a single, ready-to-move distributable called "a package". 83 84 For additional information, see the [Creating a package](./5-jackal-tutorials/0-creating-a-jackal-package.md) section. 85 86 ### (2) Ship the Package to the System Location 87 88 Jackal enables secure software delivery for various environments, such as remote, constrained, standalone, and air-gapped systems. Considering there are various target environments with their own appropriate transferring mechanisms, Jackal does not determine _how_ packages are moved so long as they can arrive in your downstream environment. See [Package Sources](./4-deploy-a-jackal-package/2-package-sources.md) for more information on where Jackal packages can be stored / pulled from. 89 90 ### (3) Deploy the Package 91 92 Once your package has arrived, you will need to: 93 94 1. Install the binary onto the system. 95 2. Initialize a cluster with a jackal init package (`jackal init`) 96 3. Deploy the package to your cluster (`jackal package deploy`) 97 98 ## Cluster Configuration Options 99 100 Jackal allows the package to either deploy to a K3s cluster it creates or an existing K8s cluster. This configuration is available on deployment of the init package. 101 102 ### Initialize `k3s` as an Appliance 103 104  105 106 In the simplest usage scenario, you deploy the Jackal init package's builtin cluster and use it to serve your application(s) directly to end users. This configuration runs Jackal and it's init package components as a self-contained appliance and is intended for use in environments where you want to run K8s-native tooling but need to keep a small footprint (i.e. single-purpose/constrained/"Edge" environments). 107 108 ### Initialize `k3s` as a Utility Cluster 109 110  111 112 In a more complex use case, you deploy the Jackal init package's builtin cluster and use it to serve resources to further downstream clusters. This configuration makes your Jackal deployment a utility cluster in service of a larger system and is intended for use in places where you want to run independent, full-service production environments with their own lifecycles but you want help tracking, caching and disseminating system/dependency updates. 113 114 ### Skip `k3s` and Initialize to an Existing Cluster 115 116  117 118 In this use case, you configure Jackal to initialize a cluster that already exists within your environment, and use that existing cluster to host and serve your applications. This configuration is intended for environments that may already have some supporting infrastructure such as disconnected / highly regulated cloud environments. 119 120 ## Why Use Jackal? 121 122 - 💸 **Free and Open-Source.** Jackal will always be free to use and maintained by the open-source community. 123 - ⭐️ **Zero Dependencies.** As a statically compiled binary, the Jackal CLI has zero dependencies to run on any machine. 124 - 🔓 **No Vendor Lock.** There is no proprietary software that locks you into using Jackal. If you want to remove it, you still can use your helm charts to deploy your software manually. 125 - 💻 **OS Agnostic.** Jackal supports numerous operating systems. A full matrix of supported OSes, architectures and featuresets is coming soon. 126 - 📦 **Highly Distributable.** Integrate and deploy software from multiple secure development environments including edge, embedded systems, secure cloud, data centers, and even local environments. 127 - 🚀 **Develop Connected, Deploy Disconnected.** Teams can build and configure individual applications or entire DevSecOps environments while connected to the internet. Once created, they can be packaged and shipped to a disconnected environment to be deployed. 128 - 💿 **Single File Deployments.** Jackal allows you to package the parts of the internet your app needs into a single compressed file to be installed without connectivity. 129 - ♻️ **Declarative Deployments.** Jackal packages define the precise state for your application enabling it to be deployed the same way every time. 130 - 🦖 **Inherit Legacy Code.** Jackal packages can wrap legacy code and projects - allowing them to be deployed to modern DevSecOps environments. 131 132 ## Features 133 134 <!-- mirrored from the project's README.md --> 135 136 ### 📦 Out of the Box Features 137 138 - Automate Kubernetes deployments in disconnected environments 139 - Automate [Software Bill of Materials (SBOM)](./3-create-a-jackal-package/6-package-sboms.md) generation 140 - Build and [publish packages as OCI image artifacts](./5-jackal-tutorials/7-publish-and-deploy.md) 141 - Provide a [web dashboard](./4-deploy-a-jackal-package/4-view-sboms.md) for viewing SBOM output 142 - Create and verify package signatures with [cosign](https://github.com/sigstore/cosign) 143 - [Publish](./2-the-jackal-cli/100-cli-commands/jackal_package_publish.md), [pull](./2-the-jackal-cli/100-cli-commands/jackal_package_pull.md), and [deploy](./2-the-jackal-cli/100-cli-commands/jackal_package_deploy.md) packages from an [OCI registry](https://opencontainers.org/) 144 - Powerful component lifecycle [actions](./3-create-a-jackal-package/7-component-actions.md) 145 - Deploy a new cluster while fully disconnected with [K3s](https://k3s.io/) or into any existing cluster using a [kube config](https://kubernetes.io/docs/concepts/configuration/organize-cluster-access-kubeconfig/) 146 - Builtin logging stack with [Loki](https://grafana.com/oss/loki/) 147 - Builtin Git server with [Gitea](https://gitea.com/) 148 - Builtin Docker registry 149 - Builtin [K9s Dashboard](https://k9scli.io/) for managing a cluster from the terminal 150 - [Mutating Webhook](adr/0005-mutating-webhook.md) to automatically update Kubernetes pod's image path and pull secrets as well as [Flux Git Repository](https://fluxcd.io/docs/components/source/gitrepositories/) URLs and secret references 151 - Builtin [command to find images](./2-the-jackal-cli/100-cli-commands/jackal_dev_find-images.md) and resources from a Helm chart 152 - Tunneling capability to [connect to Kubernetes resources](./2-the-jackal-cli/100-cli-commands/jackal_connect.md) without network routing, DNS, TLS or Ingress configuration required 153 154 ### 🛠️ Configurable Features 155 156 - Customizable [variables and package templates](examples/variables/README.md) with defaults and user prompting 157 - [Composable packages](./3-create-a-jackal-package/2-jackal-components.md#composing-package-components) to include multiple sub-packages/components 158 - Component-level OS/architecture filtering 159 160 :::tip 161 162 To quickly try out Jackal for yourself see the [Jackal Quick Start](./1-getting-started/index.md#quick-start)! 163 164 :::