diff --git a/docs/docusaurus.config.js b/docs/docusaurus.config.js index c839a4f2a..b26d3c398 100644 --- a/docs/docusaurus.config.js +++ b/docs/docusaurus.config.js @@ -30,6 +30,7 @@ const config = { ({ docs: { versions: { + "0.9": {label: "0.9", banner: "none", path: "0.9"}, "0.8": { label: "0.8", banner: "none", path: "0.8" }, "0.7": { label: "0.7", banner: "none", path: "0.7" }, "0.6": { label: "0.6", banner: "none", path: "0.6" }, diff --git a/docs/versioned_docs/version-0.10/10-home.md b/docs/versioned_docs/version-0.10/10-home.md new file mode 100644 index 000000000..c886c2b2b --- /dev/null +++ b/docs/versioned_docs/version-0.10/10-home.md @@ -0,0 +1,140 @@ +--- +title: Home +slug: / +--- + +:::caution + +Acorn is a work in progress. Features will evolve over time and there may be breaking changes between releases. Please give us your feedback in [Slack](https://slack.acorn.io), [Discussions](https://github.com/acorn-io/runtime/discussions), or [Issues](https://github.com/acorn-io/runtime/issues)! +::: + +:::note +These are the docs for installing and running Acorn runtime on your own Kubernetes clusters. To learn how to use Acorn to package and deploy your applications, and the Acorn hosted platform please visit [docs.acorn.io](https://docs.acorn.io). +::: + +## Overview + +### What is Acorn? + +Acorn is an application packaging and deployment framework that simplifies running apps on Kubernetes. Acorn is able to package up all of an application's Docker images, configuration, and deployment specifications into a single Acorn image artifact. This artifact is publishable to any OCI container registry allowing it to be deployed on any dev, test, or production Kubernetes. The portability of Acorn images enables developers to develop applications locally and move to production without having to switch tools or technology stacks. + +Developers create Acorn images by describing the application configuration in an [Acornfile](https://docs.acorn.io/authoring/overview). The Acornfile describes the whole application without all of the boilerplate of Kubernetes YAML files. The Acorn CLI is used to build, deploy, and operate Acorn images on any Kubernetes cluster. + +### Acorn Workflow + +The following figure illustrates the steps a user takes when using Acorn. + +1. The user authors an Acornfile to describe the application. +2. The user invokes the Acorn CLI to build an Acorn image from the Acornfile. +3. The Acorn image is pushed to an OCI registry. +4. The user invokes the Acorn CLI to deploy the Acorn image onto an Acorn runtime, which can be installed on any Kubernetes cluster. + +![Acorn Workflow](/img/acorn.workflow.png) + +### Acorn vs. Helm + +Helm is a popular package manager for Kubernetes. After working with Helm charts for many years, we built Acorn +specifically to offer a simplified application deployment experience for Kubernetes. Here are some of the +differences between Acorn and Helm. + +1. Helm charts are templates for Kubernetes YAML files, whereas Acornfiles define application-level constructs. Acorn is +a layer of abstraction on top of Kubernetes. Acorn users do not work with Kubernetes YAML files directly. By design, no Kubernetes +knowledge is needed to use Acorn. + +2. Helm users can package any Kubernetes workload into Helm charts, whereas Acorn is designed to package applications and not +system-level drivers, plugins, and agents. Acorn supports any type of application, stateless and stateful. Applications +run in their own namespaces. Applications do not need privileged containers. Applications run on Kubernetes but do not call the +underlying Kubernetes API or use the underlying etcd as a database by defining custom resources. + +3. Acornfiles define application-level constructs such as Docker containers, application configuration, and application +deployment specifications. Acorn brings structure to application deployment on Kubernetes. This is in marked contrast with +unconstrained use of Kubernetes YAML files in Helm charts. + +We hope Acorn will simplify packaging and deployment of applications on Kubernetes. + +## Quickstart + +### Prerequisites + +To try out Acorn you will need admin access to a Kubernetes cluster. Docker Desktop, Rancher Desktop, and K3s are all great options for trying out Acorn for testing/development. + +### Install + +On Linux and macOS you can use `brew` to quickly install Acorn. + +```shell +# Linux or macOS +brew install acorn-io/cli/acorn + +# verify binary (assume local directory) +acorn -v +``` + +For Windows and binary installs see the [installation docs](30-installation/01-installing.md#binary-install). + +### Initialize Acorn on Kubernetes cluster + +Before using Acorn on your cluster you need to initialize Acorn by running: + +```shell +acorn install +``` + +:::note +Acorn has a handful of installation requirements. If you're installing to your desktop Kubernetes cluster, you likely meet the requirements. If you're installing into a remote cluster, please review the detailed [installation instructions](30-installation/01-installing.md). +::: + +You will only need to do this once per cluster. + +### Build/Run First Acorn app + +Create a new `Acornfile` in your working directory and add the following contents. + +```acorn +containers: { + web: { + image: "nginx" + ports: publish: "80/http" + files: { + // Simple index.html file + "/usr/share/nginx/html/index.html": "

My First Acorn!

" + } + } +} +``` + +Save the file. What this file defines is a container called `web` based on the nginx container image from DockerHub. It also declares that port 80 should be exposed and that it will expose an http protocol service. We are also customizing the `index.html` file as part of our packaging process. The contents of the file will be added during the build process. + +Now you will need to build your Acorn from this file by typing `acorn build .`. This will launch an Acorn builder and development registry into your Kubernetes cluster and build the Acorn image. + +```shell +acorn run . +#[+] Building 0.8s (5/5) FINISHED +# => [internal] load .dockerignore +# => => transferring context: 2B +# ... +#green-bush + +``` + +Our Acorn has started and is named `green-bush`. + +To check the status of our app we can run the following. + +```shell +acorn apps green-bush +#NAME IMAGE HEALTHY UPTODATE CREATED ENDPOINTS MESSAGE +#green-bush 60d803258f7aa2680e4910c526485488949835728a2bc3519c09f1b6b3be1bb3 1 1 About a minute ago http://web-nginx-green-bush-6cc6aeba547e.local.oss-acorn.io => web:80 OK +``` + +In Chrome or Firefox browsers you can now open the URL listed under the endpoints column to see our app. + +Next you can learn more about what you can do with Acorn in the [getting started](37-getting-started.md) guide. + +## Next steps + +* [Installation](30-installation/01-installing.md) +* [Getting Started](37-getting-started.md) +* [Authoring Acornfiles](https://docs.acorn.io/authoring/overview) +* [Hands On Running Acorn Apps](https://docs.acorn.io/hands-on-with-acorn) +* [Join our Slack channel](https://slack.acorn.io) diff --git a/docs/versioned_docs/version-0.10/100-reference/01-command-line/_category_.yaml b/docs/versioned_docs/version-0.10/100-reference/01-command-line/_category_.yaml new file mode 100644 index 000000000..a3cffda75 --- /dev/null +++ b/docs/versioned_docs/version-0.10/100-reference/01-command-line/_category_.yaml @@ -0,0 +1 @@ +label: 'Command Line' diff --git a/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn.md b/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn.md new file mode 100644 index 000000000..8726ddcc3 --- /dev/null +++ b/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn.md @@ -0,0 +1,66 @@ +--- +title: "acorn" +--- +## acorn + + + +### Synopsis + +Acorn: Containerized Application Packaging Framework + +``` +acorn [flags] +``` + +### Options + +``` + --config-file string Path of the acorn config file to use + --debug Enable debug logging + --debug-level int Debug log level (valid 0-9) (default 7) + -h, --help help for acorn + --kubeconfig string Explicitly use kubeconfig file, overriding the default context + -j, --project string Project to work in +``` + +### SEE ALSO + +* [acorn all](acorn_all.md) - List (almost) all objects +* [acorn build](acorn_build.md) - Build an app from a Acornfile file +* [acorn check](acorn_check.md) - Check if the cluster is ready for Acorn +* [acorn container](acorn_container.md) - Manage containers +* [acorn copy](acorn_copy.md) - Copy Acorn images between registries +* [acorn credential](acorn_credential.md) - Manage registry credentials +* [acorn dashboard](acorn_dashboard.md) - Open the web dashboard for the project +* [acorn dev](acorn_dev.md) - Run an app from an image or Acornfile in dev mode or attach a dev session to a currently running app +* [acorn edit](acorn_edit.md) - Edits an acorn or secret interactively. The things you can change with acorn edit are the same things you can set via the CLI when running acorn run. +* [acorn events](acorn_events.md) - List events about Acorn resources +* [acorn exec](acorn_exec.md) - Run a command in a container +* [acorn fmt](acorn_fmt.md) - Format an Acornfile +* [acorn image](acorn_image.md) - Manage images +* [acorn info](acorn_info.md) - Info about acorn installation +* [acorn install](acorn_install.md) - Install and configure acorn in the cluster +* [acorn job](acorn_job.md) - Manage jobs +* [acorn login](acorn_login.md) - Add registry credentials +* [acorn logout](acorn_logout.md) - Remove registry credentials +* [acorn logs](acorn_logs.md) - Log all workloads from an app +* [acorn offerings](acorn_offerings.md) - Show infrastructure offerings +* [acorn port-forward](acorn_port-forward.md) - Forward a container port locally +* [acorn project](acorn_project.md) - Manage projects +* [acorn ps](acorn_ps.md) - List or get apps +* [acorn pull](acorn_pull.md) - Pull an image from a remote registry +* [acorn push](acorn_push.md) - Push an image to a remote registry +* [acorn render](acorn_render.md) - Evaluate and display an Acornfile with args +* [acorn rm](acorn_rm.md) - Delete an acorn, optionally with it's associated secrets and volumes +* [acorn run](acorn_run.md) - Run an app from an image or Acornfile +* [acorn secret](acorn_secret.md) - Manage secrets +* [acorn start](acorn_start.md) - Start an app +* [acorn stop](acorn_stop.md) - Stop an app +* [acorn tag](acorn_tag.md) - Tag an image +* [acorn uninstall](acorn_uninstall.md) - Uninstall acorn and associated resources +* [acorn update](acorn_update.md) - Update a deployed Acorn +* [acorn version](acorn_version.md) - Version information for acorn +* [acorn volume](acorn_volume.md) - Manage volumes +* [acorn wait](acorn_wait.md) - Wait an app to be ready then exit with status code 0 + diff --git a/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_all.md b/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_all.md new file mode 100644 index 000000000..b93de0102 --- /dev/null +++ b/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_all.md @@ -0,0 +1,42 @@ +--- +title: "acorn all" +--- +## acorn all + +List (almost) all objects + +``` +acorn all [flags] +``` + +### Examples + +``` + +acorn all +``` + +### Options + +``` + -a, --all Include stopped apps/containers + -h, --help help for all + -i, --images Include images in output + -o, --output string Output format (json, yaml, {{gotemplate}}) + -q, --quiet Output only names +``` + +### Options inherited from parent commands + +``` + --config-file string Path of the acorn config file to use + --debug Enable debug logging + --debug-level int Debug log level (valid 0-9) (default 7) + --kubeconfig string Explicitly use kubeconfig file, overriding the default context + -j, --project string Project to work in +``` + +### SEE ALSO + +* [acorn](acorn.md) - + diff --git a/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_app.mdx b/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_app.mdx new file mode 100644 index 000000000..c1f25093c --- /dev/null +++ b/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_app.mdx @@ -0,0 +1,5 @@ + +import {Redirect} from "@docusaurus/router"; + + diff --git a/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_build.md b/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_build.md new file mode 100644 index 000000000..14257602e --- /dev/null +++ b/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_build.md @@ -0,0 +1,48 @@ +--- +title: "acorn build" +--- +## acorn build + +Build an app from a Acornfile file + +### Synopsis + +Build all dependent container and app images from your Acornfile file + +``` +acorn build [flags] DIRECTORY +``` + +### Examples + +``` + +# Build from Acornfile file in the local directory +acorn build . +``` + +### Options + +``` + --args-file string Default args to apply to the build (default ".build-args.acorn") + -f, --file string Name of the build file (default "DIRECTORY/Acornfile") + -h, --help help for build + -p, --platform strings Target platforms (form os/arch[/variant][:osversion] example linux/amd64) + --push Push image after build + -t, --tag strings Apply a tag to the final build +``` + +### Options inherited from parent commands + +``` + --config-file string Path of the acorn config file to use + --debug Enable debug logging + --debug-level int Debug log level (valid 0-9) (default 7) + --kubeconfig string Explicitly use kubeconfig file, overriding the default context + -j, --project string Project to work in +``` + +### SEE ALSO + +* [acorn](acorn.md) - + diff --git a/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_check.md b/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_check.md new file mode 100644 index 000000000..e3fbd6fb2 --- /dev/null +++ b/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_check.md @@ -0,0 +1,43 @@ +--- +title: "acorn check" +--- +## acorn check + +Check if the cluster is ready for Acorn + +``` +acorn check [flags] +``` + +### Examples + +``` + +acorn check +``` + +### Options + +``` + -h, --help help for check + -i, --image string Override the image used for test deployments. + --ingress-class-name string Specify ingress class used for tests + -o, --output string Output format (json, yaml, {{gotemplate}}) + -q, --quiet No Results. Success or Failure only. + -n, --test-namespace string Specify namespace used for tests +``` + +### Options inherited from parent commands + +``` + --config-file string Path of the acorn config file to use + --debug Enable debug logging + --debug-level int Debug log level (valid 0-9) (default 7) + --kubeconfig string Explicitly use kubeconfig file, overriding the default context + -j, --project string Project to work in +``` + +### SEE ALSO + +* [acorn](acorn.md) - + diff --git a/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_container.md b/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_container.md new file mode 100644 index 000000000..e0b6ddf62 --- /dev/null +++ b/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_container.md @@ -0,0 +1,42 @@ +--- +title: "acorn container" +--- +## acorn container + +Manage containers + +``` +acorn container [flags] [ACORN_NAME|CONTAINER_NAME...] +``` + +### Examples + +``` + +acorn containers +``` + +### Options + +``` + -a, --all Include stopped containers + -h, --help help for container + -o, --output string Output format (json, yaml, {{gotemplate}}) + -q, --quiet Output only names +``` + +### Options inherited from parent commands + +``` + --config-file string Path of the acorn config file to use + --debug Enable debug logging + --debug-level int Debug log level (valid 0-9) (default 7) + --kubeconfig string Explicitly use kubeconfig file, overriding the default context + -j, --project string Project to work in +``` + +### SEE ALSO + +* [acorn](acorn.md) - +* [acorn container kill](acorn_container_kill.md) - Delete a container + diff --git a/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_container_kill.md b/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_container_kill.md new file mode 100644 index 000000000..f456864bf --- /dev/null +++ b/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_container_kill.md @@ -0,0 +1,41 @@ +--- +title: "acorn container kill" +--- +## acorn container kill + +Delete a container + +``` +acorn container kill [CONTAINER_NAME...] [flags] +``` + +### Examples + +``` + +acorn container kill app-name.containername-generated-hash +``` + +### Options + +``` + -h, --help help for kill +``` + +### Options inherited from parent commands + +``` + -a, --all Include stopped containers + --config-file string Path of the acorn config file to use + --debug Enable debug logging + --debug-level int Debug log level (valid 0-9) (default 7) + --kubeconfig string Explicitly use kubeconfig file, overriding the default context + -o, --output string Output format (json, yaml, {{gotemplate}}) + -j, --project string Project to work in + -q, --quiet Output only names +``` + +### SEE ALSO + +* [acorn container](acorn_container.md) - Manage containers + diff --git a/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_copy.md b/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_copy.md new file mode 100644 index 000000000..7020a2d38 --- /dev/null +++ b/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_copy.md @@ -0,0 +1,50 @@ +--- +title: "acorn copy" +--- +## acorn copy + +Copy Acorn images between registries + +``` +acorn copy [flags] SOURCE DESTINATION + + This command copies Acorn images between remote image registries. + It does not interact with images stored in the Acorn internal registry, or with the Acorn API in any way. + To set up credentials for a registry, use 'acorn login -l '. It only works with locally stored credentials. +``` + +### Examples + +``` + # Copy an image from Docker Hub to GHCR: + acorn copy docker.io//myimage:v1 ghcr.io//myimage:v1 + + # Copy the 'main' tag on an image to the 'prod' tag on the same image, and overwrite if it already exists: + acorn copy docker.io//myimage:main prod --force + + # Copy all tags on a particular image repo in Docker Hub to GHCR: + acorn copy --all-tags docker.io//myimage ghcr.io//myimage +``` + +### Options + +``` + -a, --all-tags Copy all tags of the image + -f, --force Overwrite the destination image if it already exists + -h, --help help for copy +``` + +### Options inherited from parent commands + +``` + --config-file string Path of the acorn config file to use + --debug Enable debug logging + --debug-level int Debug log level (valid 0-9) (default 7) + --kubeconfig string Explicitly use kubeconfig file, overriding the default context + -j, --project string Project to work in +``` + +### SEE ALSO + +* [acorn](acorn.md) - + diff --git a/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_credential.md b/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_credential.md new file mode 100644 index 000000000..6f755f989 --- /dev/null +++ b/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_credential.md @@ -0,0 +1,42 @@ +--- +title: "acorn credential" +--- +## acorn credential + +Manage registry credentials + +``` +acorn credential [flags] [SERVER_ADDRESS...] +``` + +### Examples + +``` + +acorn credential +``` + +### Options + +``` + -h, --help help for credential + -o, --output string Output format (json, yaml, {{gotemplate}}) + -q, --quiet Output only names +``` + +### Options inherited from parent commands + +``` + --config-file string Path of the acorn config file to use + --debug Enable debug logging + --debug-level int Debug log level (valid 0-9) (default 7) + --kubeconfig string Explicitly use kubeconfig file, overriding the default context + -j, --project string Project to work in +``` + +### SEE ALSO + +* [acorn](acorn.md) - +* [acorn credential login](acorn_credential_login.md) - Add registry credentials +* [acorn credential logout](acorn_credential_logout.md) - Remove registry credentials + diff --git a/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_credential_login.md b/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_credential_login.md new file mode 100644 index 000000000..75f9458ed --- /dev/null +++ b/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_credential_login.md @@ -0,0 +1,46 @@ +--- +title: "acorn credential login" +--- +## acorn credential login + +Add registry credentials + +``` +acorn credential login [flags] [SERVER_ADDRESS] +``` + +### Examples + +``` + +acorn login ghcr.io +``` + +### Options + +``` + -h, --help help for login + -l, --local-storage Store credential on local client for push, pull, and build (not run) + -p, --password string Password + --password-stdin Take the password from stdin + --set-default-context Set default context for project names + --skip-checks Bypass login validation checks + -u, --username string Username +``` + +### Options inherited from parent commands + +``` + --config-file string Path of the acorn config file to use + --debug Enable debug logging + --debug-level int Debug log level (valid 0-9) (default 7) + --kubeconfig string Explicitly use kubeconfig file, overriding the default context + -o, --output string Output format (json, yaml, {{gotemplate}}) + -j, --project string Project to work in + -q, --quiet Output only names +``` + +### SEE ALSO + +* [acorn credential](acorn_credential.md) - Manage registry credentials + diff --git a/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_credential_logout.md b/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_credential_logout.md new file mode 100644 index 000000000..f3d3ee297 --- /dev/null +++ b/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_credential_logout.md @@ -0,0 +1,41 @@ +--- +title: "acorn credential logout" +--- +## acorn credential logout + +Remove registry credentials + +``` +acorn credential logout [flags] [SERVER_ADDRESS] +``` + +### Examples + +``` + +acorn logout ghcr.io +``` + +### Options + +``` + -h, --help help for logout + -l, --local-storage Delete locally stored credential (not remotely stored) +``` + +### Options inherited from parent commands + +``` + --config-file string Path of the acorn config file to use + --debug Enable debug logging + --debug-level int Debug log level (valid 0-9) (default 7) + --kubeconfig string Explicitly use kubeconfig file, overriding the default context + -o, --output string Output format (json, yaml, {{gotemplate}}) + -j, --project string Project to work in + -q, --quiet Output only names +``` + +### SEE ALSO + +* [acorn credential](acorn_credential.md) - Manage registry credentials + diff --git a/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_dashboard.md b/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_dashboard.md new file mode 100644 index 000000000..d65dce103 --- /dev/null +++ b/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_dashboard.md @@ -0,0 +1,31 @@ +--- +title: "acorn dashboard" +--- +## acorn dashboard + +Open the web dashboard for the project + +``` +acorn dashboard [flags] [ACORN] +``` + +### Options + +``` + -h, --help help for dashboard +``` + +### Options inherited from parent commands + +``` + --config-file string Path of the acorn config file to use + --debug Enable debug logging + --debug-level int Debug log level (valid 0-9) (default 7) + --kubeconfig string Explicitly use kubeconfig file, overriding the default context + -j, --project string Project to work in +``` + +### SEE ALSO + +* [acorn](acorn.md) - + diff --git a/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_dev.md b/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_dev.md new file mode 100644 index 000000000..225dcbef6 --- /dev/null +++ b/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_dev.md @@ -0,0 +1,67 @@ +--- +title: "acorn dev" +--- +## acorn dev + +Run an app from an image or Acornfile in dev mode or attach a dev session to a currently running app + +``` +acorn dev [flags] IMAGE|DIRECTORY [acorn args] +``` + +### Examples + +``` + +acorn dev +acorn dev . +acorn dev --name wandering-sound +acorn dev --name wandering-sound +acorn dev --name wandering-sound --clone [acorn args] + +``` + +### Options + +``` + --annotation strings Add annotations to the app and the resources it creates (format [type:][name:]key=value) (ex k=v, containers:k=v) + --args-file string Default args to apply to run/update command (default ".args.acorn") + --auto-upgrade Enabled automatic upgrades. + -b, --bidirectional-sync In interactive mode download changes in addition to uploading + --clone Clone the vcs repository and infer the build context for the given app allowing for local development + --compute-class strings Set computeclass for a workload in the format of workload=computeclass. Specify a single computeclass to set all workloads. (ex foo=example-class or example-class) + -e, --env strings Environment variables to set on running containers + --env-file string Default env vars to apply (default ".acorn.env") + -f, --file string Name of the build file (default "DIRECTORY/Acornfile") + -h, --help help for dev + --interval string If configured for auto-upgrade, this is the time interval at which to check for new releases (ex: 1h, 5m) + -l, --label strings Add labels to the app and the resources it creates (format [type:][name:]key=value) (ex k=v, containers:k=v) + --link strings Link external app as a service in the current app (format app-name:container-name) + -m, --memory strings Set memory for a workload in the format of workload=memory. Only specify an amount to set all workloads. (ex foo=512Mi or 512Mi) + -n, --name string Name of app to create + --notify-upgrade If true and the app is configured for auto-upgrades, you will be notified in the CLI when an upgrade is available and must confirm it + -o, --output string Output API request without creating app (json, yaml) + -p, --publish strings Publish port of application (format [public:]private) (ex 81:80) + -P, --publish-all Publish all (true) or none (false) of the defined ports of application + --region string Region in which to deploy the app, immutable + --replace Replace the app with only defined values, resetting undefined fields to default values + -s, --secret strings Bind an existing secret (format existing:sec-name) (ex: sec-name:app-secret) + --session-release-on-exit Release the session when the dev command exits (default: true) + --session-timeout string Timeout in seconds for the dev session (default "360s") + -v, --volume stringArray Bind an existing volume (format existing:vol-name,field=value) (ex: pvc-name:app-data) +``` + +### Options inherited from parent commands + +``` + --config-file string Path of the acorn config file to use + --debug Enable debug logging + --debug-level int Debug log level (valid 0-9) (default 7) + --kubeconfig string Explicitly use kubeconfig file, overriding the default context + -j, --project string Project to work in +``` + +### SEE ALSO + +* [acorn](acorn.md) - + diff --git a/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_edit.md b/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_edit.md new file mode 100644 index 000000000..bc4e2b593 --- /dev/null +++ b/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_edit.md @@ -0,0 +1,37 @@ +--- +title: "acorn edit" +--- +## acorn edit + +Edits an acorn or secret interactively. The things you can change with acorn edit are the same things you can set via the CLI when running acorn run. + +``` +acorn edit ACORN_NAME|SECRET_NAME [flags] +``` + +### Examples + +``` +acorn edit my-acorn +``` + +### Options + +``` + -h, --help help for edit +``` + +### Options inherited from parent commands + +``` + --config-file string Path of the acorn config file to use + --debug Enable debug logging + --debug-level int Debug log level (valid 0-9) (default 7) + --kubeconfig string Explicitly use kubeconfig file, overriding the default context + -j, --project string Project to work in +``` + +### SEE ALSO + +* [acorn](acorn.md) - + diff --git a/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_events.md b/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_events.md new file mode 100644 index 000000000..dcfe7888e --- /dev/null +++ b/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_events.md @@ -0,0 +1,81 @@ +--- +title: "acorn events" +--- +## acorn events + +List events about Acorn resources + +``` +acorn events [flags] [PREFIX] +``` + +### Examples + +``` +# List all events in the current project + acorn events + + # List events across all projects + acorn -A events + + + # List the last 10 events + acorn events --tail 10 + + # List the last 5 events and follow the event log + acorn events --tail 5 -f + + # Filter by Related Resource + # If a PREFIX is given in the form '/', the results of this command are pruned to include + # only those events related to resources matching the given kind and name. + # List events related to the 'hello' app in the current project + acorn events app/hello + + # If the '/' suffix is omitted, '' will match events related to any resource of the given kind. + # List events related to any app in the current project + acorn events app + + # Filter by Event Name + # If the PREFIX '/' suffix is omitted, and the '' doesn't match a known event source, its value + # is interpreted as an event name prefix. + # List events with names that begin with '4b2b' + acorn events 4b2b + + # Get a single event by name + acorn events 4b2ba097badf2031c4718609b9179fb5 + + # Filtering by Time + # The --since and --until options can be Unix timestamps, date formatted timestamps, or Go duration strings (relative to system time). + # List events observed within the last 15 minutes + acorn events --since 15m + + # List events observed between 2023-05-08T15:04:05 and 2023-05-08T15:05:05 (inclusive) + acorn events --since '2023-05-08T15:04:05' --until '2023-05-08T15:05:05' + +``` + +### Options + +``` + -f, --follow Follow the event log + -h, --help help for events + -o, --output string Output format (json, yaml, {{gotemplate}}) + -s, --since string Show all events created since timestamp + -t, --tail int Return this number of latest events + -u, --until string Stream events until this timestamp +``` + +### Options inherited from parent commands + +``` + --config-file string Path of the acorn config file to use + --debug Enable debug logging + --debug-level int Debug log level (valid 0-9) (default 7) + --kubeconfig string Explicitly use kubeconfig file, overriding the default context + -j, --project string Project to work in +``` + +### SEE ALSO + +* [acorn](acorn.md) - + diff --git a/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_exec.md b/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_exec.md new file mode 100644 index 000000000..7f5e36b04 --- /dev/null +++ b/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_exec.md @@ -0,0 +1,39 @@ +--- +title: "acorn exec" +--- +## acorn exec + +Run a command in a container + +### Synopsis + +Run a command in a container + +``` +acorn exec [flags] ACORN_NAME|CONTAINER_NAME CMD +``` + +### Options + +``` + -c, --container string Name of container to exec into + -d, --debug-image string Use image as container root for command + -h, --help help for exec + -i, --interactive Not used + -t, --tty Not used +``` + +### Options inherited from parent commands + +``` + --config-file string Path of the acorn config file to use + --debug Enable debug logging + --debug-level int Debug log level (valid 0-9) (default 7) + --kubeconfig string Explicitly use kubeconfig file, overriding the default context + -j, --project string Project to work in +``` + +### SEE ALSO + +* [acorn](acorn.md) - + diff --git a/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_fmt.md b/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_fmt.md new file mode 100644 index 000000000..03cf07989 --- /dev/null +++ b/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_fmt.md @@ -0,0 +1,31 @@ +--- +title: "acorn fmt" +--- +## acorn fmt + +Format an Acornfile + +``` +acorn fmt [flags] [ACORNFILE] +``` + +### Options + +``` + -h, --help help for fmt +``` + +### Options inherited from parent commands + +``` + --config-file string Path of the acorn config file to use + --debug Enable debug logging + --debug-level int Debug log level (valid 0-9) (default 7) + --kubeconfig string Explicitly use kubeconfig file, overriding the default context + -j, --project string Project to work in +``` + +### SEE ALSO + +* [acorn](acorn.md) - + diff --git a/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_image.md b/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_image.md new file mode 100644 index 000000000..05785d1d6 --- /dev/null +++ b/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_image.md @@ -0,0 +1,46 @@ +--- +title: "acorn image" +--- +## acorn image + +Manage images + +``` +acorn image [flags] [IMAGE_REPO:TAG|IMAGE_ID] +``` + +### Examples + +``` + +acorn images +``` + +### Options + +``` + -a, --all Include untagged images + -c, --containers Show containers for images + -h, --help help for image + --no-trunc Don't truncate IDs + -o, --output string Output format (json, yaml, {{gotemplate}}) + -q, --quiet Output only names +``` + +### Options inherited from parent commands + +``` + --config-file string Path of the acorn config file to use + --debug Enable debug logging + --debug-level int Debug log level (valid 0-9) (default 7) + --kubeconfig string Explicitly use kubeconfig file, overriding the default context + -j, --project string Project to work in +``` + +### SEE ALSO + +* [acorn](acorn.md) - +* [acorn image copy](acorn_image_copy.md) - Copy Acorn images between registries +* [acorn image details](acorn_image_details.md) - Show details of an Image +* [acorn image rm](acorn_image_rm.md) - Delete an Image + diff --git a/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_image_copy.md b/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_image_copy.md new file mode 100644 index 000000000..b48d81c91 --- /dev/null +++ b/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_image_copy.md @@ -0,0 +1,50 @@ +--- +title: "acorn image copy" +--- +## acorn image copy + +Copy Acorn images between registries + +``` +acorn image copy [flags] SOURCE DESTINATION + + This command copies Acorn images between remote image registries. + It does not interact with images stored in the Acorn internal registry, or with the Acorn API in any way. + To set up credentials for a registry, use 'acorn login -l '. It only works with locally stored credentials. +``` + +### Examples + +``` + # Copy an image from Docker Hub to GHCR: + acorn copy docker.io//myimage:v1 ghcr.io//myimage:v1 + + # Copy the 'main' tag on an image to the 'prod' tag on the same image, and overwrite if it already exists: + acorn copy docker.io//myimage:main prod --force + + # Copy all tags on a particular image repo in Docker Hub to GHCR: + acorn copy --all-tags docker.io//myimage ghcr.io//myimage +``` + +### Options + +``` + -a, --all-tags Copy all tags of the image + -f, --force Overwrite the destination image if it already exists + -h, --help help for copy +``` + +### Options inherited from parent commands + +``` + --config-file string Path of the acorn config file to use + --debug Enable debug logging + --debug-level int Debug log level (valid 0-9) (default 7) + --kubeconfig string Explicitly use kubeconfig file, overriding the default context + -j, --project string Project to work in +``` + +### SEE ALSO + +* [acorn image](acorn_image.md) - Manage images + diff --git a/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_image_details.md b/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_image_details.md new file mode 100644 index 000000000..7e28c1e59 --- /dev/null +++ b/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_image_details.md @@ -0,0 +1,38 @@ +--- +title: "acorn image details" +--- +## acorn image details + +Show details of an Image + +``` +acorn image details IMAGE_NAME [NESTED DIGEST] [flags] +``` + +### Examples + +``` +acorn image details my-image +``` + +### Options + +``` + -h, --help help for details + -o, --output string Output format (json, yaml, aml) (default "aml") +``` + +### Options inherited from parent commands + +``` + --config-file string Path of the acorn config file to use + --debug Enable debug logging + --debug-level int Debug log level (valid 0-9) (default 7) + --kubeconfig string Explicitly use kubeconfig file, overriding the default context + -j, --project string Project to work in +``` + +### SEE ALSO + +* [acorn image](acorn_image.md) - Manage images + diff --git a/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_image_rm.md b/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_image_rm.md new file mode 100644 index 000000000..2599aced0 --- /dev/null +++ b/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_image_rm.md @@ -0,0 +1,38 @@ +--- +title: "acorn image rm" +--- +## acorn image rm + +Delete an Image + +``` +acorn image rm [IMAGE_NAME...] [flags] +``` + +### Examples + +``` +acorn image rm my-image +``` + +### Options + +``` + -f, --force Force Delete + -h, --help help for rm +``` + +### Options inherited from parent commands + +``` + --config-file string Path of the acorn config file to use + --debug Enable debug logging + --debug-level int Debug log level (valid 0-9) (default 7) + --kubeconfig string Explicitly use kubeconfig file, overriding the default context + -j, --project string Project to work in +``` + +### SEE ALSO + +* [acorn image](acorn_image.md) - Manage images + diff --git a/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_info.md b/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_info.md new file mode 100644 index 000000000..a6384a4a6 --- /dev/null +++ b/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_info.md @@ -0,0 +1,33 @@ +--- +title: "acorn info" +--- +## acorn info + +Info about acorn installation + +``` +acorn info [flags] +``` + +### Options + +``` + -A, --all-projects Include all projects to all currently logged in servers + -h, --help help for info + -o, --output string Output format (json, yaml, {{gotemplate}}) (default "yaml") +``` + +### Options inherited from parent commands + +``` + --config-file string Path of the acorn config file to use + --debug Enable debug logging + --debug-level int Debug log level (valid 0-9) (default 7) + --kubeconfig string Explicitly use kubeconfig file, overriding the default context + -j, --project string Project to work in +``` + +### SEE ALSO + +* [acorn](acorn.md) - + diff --git a/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_install.md b/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_install.md new file mode 100644 index 000000000..b7f9465fa --- /dev/null +++ b/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_install.md @@ -0,0 +1,94 @@ +--- +title: "acorn install" +--- +## acorn install + +Install and configure acorn in the cluster + +``` +acorn install [flags] +``` + +### Examples + +``` + +acorn install +``` + +### Options + +``` + --acorn-dns string enabled|disabled|auto. If enabled, containers created by Acorn will get public FQDNs. Auto functions as disabled if a custom clusterDomain has been supplied (default auto) + --acorn-dns-endpoint string The URL to access the Acorn DNS service + --allow-traffic-from-namespace strings Namespaces that are allowed to send network traffic to all Acorn apps + --allow-user-annotation strings Allow these annotations to propagate to dependent objects, no effect if --ignore-user-labels-and-annotations not true + --allow-user-label strings Allow these labels to propagate to dependent objects, no effect if --ignore-user-labels-and-annotations not true + --allow-user-metadata-namespace strings Allow these namespaces to propagate labels and annotations to dependent objects, no effect if --ignore-user-labels-and-annotations not true + --api-server-cpu string The CPU to allocate to the runtime-api-server in the format of : (example 200m:1000m) + --api-server-memory string The memory to allocate to the runtime-api-server in the format of : (example 256Mi:1Gi) + --api-server-pod-annotations stringArray annotations to apply to acorn-api pods + --api-server-replicas int acorn-api deployment replica count + --auto-configure-karpenter-dont-evict-annotations Automatically configure Karpenter to not evict pods with the given annotations if app is running a single replica. (default false) + --auto-upgrade-interval string For apps configured with automatic upgrades enabled, the interval at which to check for new versions. Upgrade intervals configured at the application level cannot be smaller than this. (default '5m' - 5 minutes) + --aws-identity-provider-arn string ARN of cluster's OpenID Connect provider registered in AWS + --builder-per-project Create a dedicated builder per project + --buildkitd-cpu string The CPU to allocate to buildkitd in the format of : (example 200m:1000m) + --buildkitd-memory string The memory to allocate to buildkitd in the format of : (example 256Mi:1Gi) + --buildkitd-service-cpu string The CPU to allocate to the buildkitd service in the format of : (example 200m:1000m) + --buildkitd-service-memory string The memory to allocate to the buildkitd service in the format of : (example 256Mi:1Gi) + --cert-manager-issuer string The name of the cert-manager cluster issuer to use for TLS certificates on custom domains + --cluster-domain strings The externally addressable cluster domain (default .oss-acorn.io) + --controller-cpu string The CPU to allocate to the runtime-controller in the format of : (example 200m:1000m) + --controller-memory string The memory to allocate to the runtime-controller in the format of : (example 256Mi:1Gi) + --controller-replicas int acorn-controller deployment replica count + --controller-service-account-annotation strings annotation to apply to the acorn-system service account + --event-ttl string Amount of time an Acorn event will be stored before being deleted (default '168h' - 7 days) + --features strings Enable or disable features. (example foo=true,bar=false) + -h, --help help for install + --http-endpoint-pattern string Go template for formatting application http endpoints. Valid variables to use are: App, Container, Namespace, Hash and ClusterDomain. (default pattern is {{hashConcat 8 .Container .App .Namespace | truncate}}.{{.ClusterDomain}}) + --ignore-resource-requirements Ignore memory and CPU requests and limits, intended for local development (default is false) + --ignore-user-labels-and-annotations Don't propagate user-defined labels and annotations to dependent objects + --image string Override the default image used for the deployment + --ingress-class-name string The ingress class name to assign to all created ingress resources (default '') + --ingress-controller-namespace string The namespace where the ingress controller runs - used to secure published HTTP ports with NetworkPolicies. + --internal-cluster-domain string The Kubernetes internal cluster domain (default svc.cluster.local) + --internal-registry-prefix string The image prefix to use when pushing internal images (example ghcr.io/my-org/) + --lets-encrypt string enabled|disabled|staging. If enabled, acorn generated endpoints will be secured using TLS certificate from Let's Encrypt. Staging uses Let's Encrypt's staging environment. (default disabled) + --lets-encrypt-email string Required if --lets-encrypt=enabled. The email address to use for Let's Encrypt registration(default '') + --lets-encrypt-tos-agree Required if --lets-encrypt=enabled. If true, you agree to the Let's Encrypt terms of service (default false) + --manage-volume-classes Manually manage volume classes rather than sync with storage classes, setting to 'true' will delete Acorn-created volume classes + --network-policies Create Kubernetes NetworkPolicies which block cross-project network traffic (default false) + -o, --output string Output manifests instead of applying them (json, yaml) + --pod-security-enforce-profile string The name of the PodSecurity profile to set (default baseline) + --profile string The name of the profile to use for the installation. Profiles options are production (prod) and default. (default profile is default) + --propagate-project-annotation strings The list of keys of annotations to propagate from acorn project to app namespaces + --propagate-project-label strings The list of keys of labels to propagate from acorn project to app namespaces + --publish-builders Publish the builders through ingress to so build traffic does not traverse the api-server + --quiet Only output errors encountered during installation + --record-builds Keep a record of each acorn build that happens + --registry-cpu string The CPU to allocate to the registry in the format of : (example 200m:1000m) + --registry-memory string The memory to allocate to the registry in the format of : (example 256Mi:1Gi) + --service-lb-annotation strings Annotation to add to the service of type LoadBalancer. Defaults to empty. (example key=value) + --set-pod-security-enforce-profile Set the PodSecurity profile on created namespaces (default true) + --skip-checks Bypass installation checks + --use-custom-ca-bundle Use CA bundle for admin supplied secret for all acorn control plane components. Defaults to false. + --volume-size-default string Set the default size for acorn volumes. Accepts storage suffixes (K, M, G, Ki, Mi, Gi, etc) and "." and "_" separators (default 0) + -m, --workload-memory-default string Set the default memory for acorn workloads. Accepts binary suffixes (Ki, Mi, Gi, etc) and "." and "_" separators (default 0) + --workload-memory-maximum string Set the maximum memory for acorn workloads. Accepts binary suffixes (Ki, Mi, Gi, etc) and "." and "_" separators (default 0) +``` + +### Options inherited from parent commands + +``` + --config-file string Path of the acorn config file to use + --debug Enable debug logging + --debug-level int Debug log level (valid 0-9) (default 7) + --kubeconfig string Explicitly use kubeconfig file, overriding the default context + -j, --project string Project to work in +``` + +### SEE ALSO + +* [acorn](acorn.md) - + diff --git a/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_job.md b/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_job.md new file mode 100644 index 000000000..fc31136db --- /dev/null +++ b/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_job.md @@ -0,0 +1,41 @@ +--- +title: "acorn job" +--- +## acorn job + +Manage jobs + +``` +acorn job [flags] [ACORN_NAME|JOB_NAME...] +``` + +### Examples + +``` + +acorn jobs +``` + +### Options + +``` + -h, --help help for job + -o, --output string Output format (json, yaml, {{gotemplate}}) + -q, --quiet Output only names +``` + +### Options inherited from parent commands + +``` + --config-file string Path of the acorn config file to use + --debug Enable debug logging + --debug-level int Debug log level (valid 0-9) (default 7) + --kubeconfig string Explicitly use kubeconfig file, overriding the default context + -j, --project string Project to work in +``` + +### SEE ALSO + +* [acorn](acorn.md) - +* [acorn job restart](acorn_job_restart.md) - Restart a job + diff --git a/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_job_restart.md b/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_job_restart.md new file mode 100644 index 000000000..86978a4bf --- /dev/null +++ b/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_job_restart.md @@ -0,0 +1,40 @@ +--- +title: "acorn job restart" +--- +## acorn job restart + +Restart a job + +``` +acorn job restart [JOB_NAME...] [flags] +``` + +### Examples + +``` + +acorn job restart app-name.job-name +``` + +### Options + +``` + -h, --help help for restart +``` + +### Options inherited from parent commands + +``` + --config-file string Path of the acorn config file to use + --debug Enable debug logging + --debug-level int Debug log level (valid 0-9) (default 7) + --kubeconfig string Explicitly use kubeconfig file, overriding the default context + -o, --output string Output format (json, yaml, {{gotemplate}}) + -j, --project string Project to work in + -q, --quiet Output only names +``` + +### SEE ALSO + +* [acorn job](acorn_job.md) - Manage jobs + diff --git a/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_login.md b/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_login.md new file mode 100644 index 000000000..5adaa5390 --- /dev/null +++ b/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_login.md @@ -0,0 +1,44 @@ +--- +title: "acorn login" +--- +## acorn login + +Add registry credentials + +``` +acorn login [flags] [SERVER_ADDRESS] +``` + +### Examples + +``` + +acorn login ghcr.io +``` + +### Options + +``` + -h, --help help for login + -l, --local-storage Store credential on local client for push, pull, and build (not run) + -p, --password string Password + --password-stdin Take the password from stdin + --set-default-context Set default context for project names + --skip-checks Bypass login validation checks + -u, --username string Username +``` + +### Options inherited from parent commands + +``` + --config-file string Path of the acorn config file to use + --debug Enable debug logging + --debug-level int Debug log level (valid 0-9) (default 7) + --kubeconfig string Explicitly use kubeconfig file, overriding the default context + -j, --project string Project to work in +``` + +### SEE ALSO + +* [acorn](acorn.md) - + diff --git a/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_logout.md b/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_logout.md new file mode 100644 index 000000000..2e832e183 --- /dev/null +++ b/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_logout.md @@ -0,0 +1,39 @@ +--- +title: "acorn logout" +--- +## acorn logout + +Remove registry credentials + +``` +acorn logout [flags] [SERVER_ADDRESS] +``` + +### Examples + +``` + +acorn logout ghcr.io +``` + +### Options + +``` + -h, --help help for logout + -l, --local-storage Delete locally stored credential (not remotely stored) +``` + +### Options inherited from parent commands + +``` + --config-file string Path of the acorn config file to use + --debug Enable debug logging + --debug-level int Debug log level (valid 0-9) (default 7) + --kubeconfig string Explicitly use kubeconfig file, overriding the default context + -j, --project string Project to work in +``` + +### SEE ALSO + +* [acorn](acorn.md) - + diff --git a/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_logs.md b/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_logs.md new file mode 100644 index 000000000..9f75000d7 --- /dev/null +++ b/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_logs.md @@ -0,0 +1,35 @@ +--- +title: "acorn logs" +--- +## acorn logs + +Log all workloads from an app + +``` +acorn logs [flags] [ACORN_NAME|CONTAINER_REPLICA_NAME] +``` + +### Options + +``` + -c, --container string Container name or Job name within app to follow + -f, --follow Follow log output + -h, --help help for logs + -s, --since string Show logs since timestamp (e.g. 42m for 42 minutes) + -n, --tail int Number of lines in log output +``` + +### Options inherited from parent commands + +``` + --config-file string Path of the acorn config file to use + --debug Enable debug logging + --debug-level int Debug log level (valid 0-9) (default 7) + --kubeconfig string Explicitly use kubeconfig file, overriding the default context + -j, --project string Project to work in +``` + +### SEE ALSO + +* [acorn](acorn.md) - + diff --git a/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_offerings.md b/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_offerings.md new file mode 100644 index 000000000..7c25c8e7c --- /dev/null +++ b/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_offerings.md @@ -0,0 +1,43 @@ +--- +title: "acorn offerings" +--- +## acorn offerings + +Show infrastructure offerings + +``` +acorn offerings [flags] command +``` + +### Examples + +``` + +acorn offerings +``` + +### Options + +``` + -h, --help help for offerings + -o, --output string Output format (json, yaml, {{gotemplate}}) + -q, --quiet Output only names +``` + +### Options inherited from parent commands + +``` + --config-file string Path of the acorn config file to use + --debug Enable debug logging + --debug-level int Debug log level (valid 0-9) (default 7) + --kubeconfig string Explicitly use kubeconfig file, overriding the default context + -j, --project string Project to work in +``` + +### SEE ALSO + +* [acorn](acorn.md) - +* [acorn offerings computeclasses](acorn_offerings_computeclasses.md) - List available ComputeClasses +* [acorn offerings regions](acorn_offerings_regions.md) - List available regions +* [acorn offerings volumeclasses](acorn_offerings_volumeclasses.md) - List available volume classes + diff --git a/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_offerings_computeclasses.md b/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_offerings_computeclasses.md new file mode 100644 index 000000000..1ce227d98 --- /dev/null +++ b/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_offerings_computeclasses.md @@ -0,0 +1,40 @@ +--- +title: "acorn offerings computeclasses" +--- +## acorn offerings computeclasses + +List available ComputeClasses + +``` +acorn offerings computeclasses [flags] [COMPUTECLASS_NAME...] +``` + +### Examples + +``` + +acorn computeclasses +``` + +### Options + +``` + -h, --help help for computeclasses + -o, --output string Output format (json, yaml, {{gotemplate}}) + -q, --quiet Output only names +``` + +### Options inherited from parent commands + +``` + --config-file string Path of the acorn config file to use + --debug Enable debug logging + --debug-level int Debug log level (valid 0-9) (default 7) + --kubeconfig string Explicitly use kubeconfig file, overriding the default context + -j, --project string Project to work in +``` + +### SEE ALSO + +* [acorn offerings](acorn_offerings.md) - Show infrastructure offerings + diff --git a/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_offerings_regions.md b/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_offerings_regions.md new file mode 100644 index 000000000..46e1d81ef --- /dev/null +++ b/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_offerings_regions.md @@ -0,0 +1,40 @@ +--- +title: "acorn offerings regions" +--- +## acorn offerings regions + +List available regions + +``` +acorn offerings regions [flags] [REGION...] +``` + +### Examples + +``` + +acorn offering regions +``` + +### Options + +``` + -h, --help help for regions + -o, --output string Output format (json, yaml, {{gotemplate}}) + -q, --quiet Output only names +``` + +### Options inherited from parent commands + +``` + --config-file string Path of the acorn config file to use + --debug Enable debug logging + --debug-level int Debug log level (valid 0-9) (default 7) + --kubeconfig string Explicitly use kubeconfig file, overriding the default context + -j, --project string Project to work in +``` + +### SEE ALSO + +* [acorn offerings](acorn_offerings.md) - Show infrastructure offerings + diff --git a/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_offerings_volumeclasses.md b/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_offerings_volumeclasses.md new file mode 100644 index 000000000..300957ca4 --- /dev/null +++ b/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_offerings_volumeclasses.md @@ -0,0 +1,40 @@ +--- +title: "acorn offerings volumeclasses" +--- +## acorn offerings volumeclasses + +List available volume classes + +``` +acorn offerings volumeclasses [flags] [VOLUME_CLASS...] +``` + +### Examples + +``` + +acorn offering volumeclasses +``` + +### Options + +``` + -h, --help help for volumeclasses + -o, --output string Output format (json, yaml, {{gotemplate}}) + -q, --quiet Output only names +``` + +### Options inherited from parent commands + +``` + --config-file string Path of the acorn config file to use + --debug Enable debug logging + --debug-level int Debug log level (valid 0-9) (default 7) + --kubeconfig string Explicitly use kubeconfig file, overriding the default context + -j, --project string Project to work in +``` + +### SEE ALSO + +* [acorn offerings](acorn_offerings.md) - Show infrastructure offerings + diff --git a/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_port-forward.md b/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_port-forward.md new file mode 100644 index 000000000..734d89401 --- /dev/null +++ b/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_port-forward.md @@ -0,0 +1,37 @@ +--- +title: "acorn port-forward" +--- +## acorn port-forward + +Forward a container port locally + +### Synopsis + +Forward a container port locally + +``` +acorn port-forward [flags] ACORN_NAME|CONTAINER_NAME PORT +``` + +### Options + +``` + --address string The IP address to listen on (default "127.0.0.1") + -c, --container string Name of container to port forward into + -h, --help help for port-forward +``` + +### Options inherited from parent commands + +``` + --config-file string Path of the acorn config file to use + --debug Enable debug logging + --debug-level int Debug log level (valid 0-9) (default 7) + --kubeconfig string Explicitly use kubeconfig file, overriding the default context + -j, --project string Project to work in +``` + +### SEE ALSO + +* [acorn](acorn.md) - + diff --git a/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_project.md b/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_project.md new file mode 100644 index 000000000..270f62938 --- /dev/null +++ b/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_project.md @@ -0,0 +1,44 @@ +--- +title: "acorn project" +--- +## acorn project + +Manage projects + +``` +acorn project [flags] +``` + +### Examples + +``` + +acorn project +``` + +### Options + +``` + -h, --help help for project + -o, --output string Output format (json, yaml, {{gotemplate}}) + -q, --quiet Output only names +``` + +### Options inherited from parent commands + +``` + --config-file string Path of the acorn config file to use + --debug Enable debug logging + --debug-level int Debug log level (valid 0-9) (default 7) + --kubeconfig string Explicitly use kubeconfig file, overriding the default context + -j, --project string Project to work in +``` + +### SEE ALSO + +* [acorn](acorn.md) - +* [acorn project create](acorn_project_create.md) - Create new project +* [acorn project rm](acorn_project_rm.md) - Deletes projects +* [acorn project update](acorn_project_update.md) - Update project +* [acorn project use](acorn_project_use.md) - Set current project + diff --git a/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_project_create.md b/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_project_create.md new file mode 100644 index 000000000..f1ed32f7c --- /dev/null +++ b/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_project_create.md @@ -0,0 +1,47 @@ +--- +title: "acorn project create" +--- +## acorn project create + +Create new project + +``` +acorn project create [flags] PROJECT_NAME [PROJECT_NAME...] +``` + +### Examples + +``` + +# Create a project locally +acorn project create my-new-project + +# Create a project on remote service acorn.io +acorn project create acorn.io/username/new-project + +``` + +### Options + +``` + --default-region string Default region for project resources + -h, --help help for create + --supported-region strings Supported regions for created project +``` + +### Options inherited from parent commands + +``` + --config-file string Path of the acorn config file to use + --debug Enable debug logging + --debug-level int Debug log level (valid 0-9) (default 7) + --kubeconfig string Explicitly use kubeconfig file, overriding the default context + -o, --output string Output format (json, yaml, {{gotemplate}}) + -j, --project string Project to work in + -q, --quiet Output only names +``` + +### SEE ALSO + +* [acorn project](acorn_project.md) - Manage projects + diff --git a/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_project_rm.md b/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_project_rm.md new file mode 100644 index 000000000..e625458ee --- /dev/null +++ b/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_project_rm.md @@ -0,0 +1,41 @@ +--- +title: "acorn project rm" +--- +## acorn project rm + +Deletes projects + +``` +acorn project rm [flags] PROJECT_NAME [PROJECT_NAME...] +``` + +### Examples + +``` + +acorn project rm my-project + +``` + +### Options + +``` + -h, --help help for rm +``` + +### Options inherited from parent commands + +``` + --config-file string Path of the acorn config file to use + --debug Enable debug logging + --debug-level int Debug log level (valid 0-9) (default 7) + --kubeconfig string Explicitly use kubeconfig file, overriding the default context + -o, --output string Output format (json, yaml, {{gotemplate}}) + -j, --project string Project to work in + -q, --quiet Output only names +``` + +### SEE ALSO + +* [acorn project](acorn_project.md) - Manage projects + diff --git a/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_project_update.md b/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_project_update.md new file mode 100644 index 000000000..d72427083 --- /dev/null +++ b/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_project_update.md @@ -0,0 +1,43 @@ +--- +title: "acorn project update" +--- +## acorn project update + +Update project + +``` +acorn project update [flags] PROJECT_NAME +``` + +### Examples + +``` + +acorn project update my-project + +``` + +### Options + +``` + --default-region string Default region for project resources + -h, --help help for update + --supported-region strings Supported regions for the created project +``` + +### Options inherited from parent commands + +``` + --config-file string Path of the acorn config file to use + --debug Enable debug logging + --debug-level int Debug log level (valid 0-9) (default 7) + --kubeconfig string Explicitly use kubeconfig file, overriding the default context + -o, --output string Output format (json, yaml, {{gotemplate}}) + -j, --project string Project to work in + -q, --quiet Output only names +``` + +### SEE ALSO + +* [acorn project](acorn_project.md) - Manage projects + diff --git a/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_project_use.md b/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_project_use.md new file mode 100644 index 000000000..4d13d5472 --- /dev/null +++ b/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_project_use.md @@ -0,0 +1,40 @@ +--- +title: "acorn project use" +--- +## acorn project use + +Set current project + +``` +acorn project use [flags] PROJECT_NAME +``` + +### Examples + +``` + +acorn project use acorn.io/my-user/acorn +``` + +### Options + +``` + -h, --help help for use +``` + +### Options inherited from parent commands + +``` + --config-file string Path of the acorn config file to use + --debug Enable debug logging + --debug-level int Debug log level (valid 0-9) (default 7) + --kubeconfig string Explicitly use kubeconfig file, overriding the default context + -o, --output string Output format (json, yaml, {{gotemplate}}) + -j, --project string Project to work in + -q, --quiet Output only names +``` + +### SEE ALSO + +* [acorn project](acorn_project.md) - Manage projects + diff --git a/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_ps.md b/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_ps.md new file mode 100644 index 000000000..0dd336859 --- /dev/null +++ b/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_ps.md @@ -0,0 +1,42 @@ +--- +title: "acorn ps" +--- +## acorn ps + +List or get apps + +``` +acorn ps [flags] [ACORN_NAME...] +``` + +### Examples + +``` + +acorn ps +``` + +### Options + +``` + -a, --all Include stopped apps + -A, --all-projects Include all projects in same Acorn instance as the current default project + -h, --help help for ps + -o, --output string Output format (json, yaml, {{gotemplate}}) + -q, --quiet Output only names +``` + +### Options inherited from parent commands + +``` + --config-file string Path of the acorn config file to use + --debug Enable debug logging + --debug-level int Debug log level (valid 0-9) (default 7) + --kubeconfig string Explicitly use kubeconfig file, overriding the default context + -j, --project string Project to work in +``` + +### SEE ALSO + +* [acorn](acorn.md) - + diff --git a/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_pull.md b/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_pull.md new file mode 100644 index 000000000..0d779f435 --- /dev/null +++ b/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_pull.md @@ -0,0 +1,35 @@ +--- +title: "acorn pull" +--- +## acorn pull + +Pull an image from a remote registry + +``` +acorn pull [flags] IMAGE +``` + +### Options + +``` + -a, --annotation strings Annotations to check for during verification + -h, --help help for pull + -k, --key string Key to use for verifying (default "./cosign.pub") + --no-verify-name Do not verify the image name in the signature + -v, --verify Verify the image signature BEFORE pulling and only pull on success +``` + +### Options inherited from parent commands + +``` + --config-file string Path of the acorn config file to use + --debug Enable debug logging + --debug-level int Debug log level (valid 0-9) (default 7) + --kubeconfig string Explicitly use kubeconfig file, overriding the default context + -j, --project string Project to work in +``` + +### SEE ALSO + +* [acorn](acorn.md) - + diff --git a/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_push.md b/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_push.md new file mode 100644 index 000000000..d5edf0592 --- /dev/null +++ b/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_push.md @@ -0,0 +1,31 @@ +--- +title: "acorn push" +--- +## acorn push + +Push an image to a remote registry + +``` +acorn push [flags] IMAGE +``` + +### Options + +``` + -h, --help help for push +``` + +### Options inherited from parent commands + +``` + --config-file string Path of the acorn config file to use + --debug Enable debug logging + --debug-level int Debug log level (valid 0-9) (default 7) + --kubeconfig string Explicitly use kubeconfig file, overriding the default context + -j, --project string Project to work in +``` + +### SEE ALSO + +* [acorn](acorn.md) - + diff --git a/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_render.md b/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_render.md new file mode 100644 index 000000000..4509af93a --- /dev/null +++ b/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_render.md @@ -0,0 +1,34 @@ +--- +title: "acorn render" +--- +## acorn render + +Evaluate and display an Acornfile with args + +``` +acorn render [flags] DIRECTORY [acorn args] +``` + +### Options + +``` + --args-file string Default args to apply to command (default ".args.acorn") + -f, --file string Name of the dev file (default "DIRECTORY/Acornfile") + -h, --help help for render + -o, --output string Output in JSON or YAML (default "aml") +``` + +### Options inherited from parent commands + +``` + --config-file string Path of the acorn config file to use + --debug Enable debug logging + --debug-level int Debug log level (valid 0-9) (default 7) + --kubeconfig string Explicitly use kubeconfig file, overriding the default context + -j, --project string Project to work in +``` + +### SEE ALSO + +* [acorn](acorn.md) - + diff --git a/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_rm.md b/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_rm.md new file mode 100644 index 000000000..cdc898536 --- /dev/null +++ b/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_rm.md @@ -0,0 +1,44 @@ +--- +title: "acorn rm" +--- +## acorn rm + +Delete an acorn, optionally with it's associated secrets and volumes + +``` +acorn rm [flags] ACORN_NAME [ACORN_NAME...] +``` + +### Examples + +``` + +acorn rm ACORN_NAME +acorn rm --volumes --secrets ACORN_NAME +``` + +### Options + +``` + -a, --all Delete all associated resources (volumes, secrets) + -f, --force Do not prompt for delete + -h, --help help for rm + --ignore-cleanup Delete acorns without running delete jobs + -s, --secrets Delete acorn and associated secrets + -v, --volumes Delete acorn and associated volumes +``` + +### Options inherited from parent commands + +``` + --config-file string Path of the acorn config file to use + --debug Enable debug logging + --debug-level int Debug log level (valid 0-9) (default 7) + --kubeconfig string Explicitly use kubeconfig file, overriding the default context + -j, --project string Project to work in +``` + +### SEE ALSO + +* [acorn](acorn.md) - + diff --git a/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_run.md b/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_run.md new file mode 100644 index 000000000..070b888c8 --- /dev/null +++ b/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_run.md @@ -0,0 +1,107 @@ +--- +title: "acorn run" +--- +## acorn run + +Run an app from an image or Acornfile + +``` +acorn run [flags] IMAGE|DIRECTORY [acorn args] +``` + +### Examples + +``` + +Running an app + - Build and run from a directory + acorn run --name my-app . + + - Run from an image + acorn run --name my-app ghcr.io/acorn-io/hello-world + +Updating an app + - Rebuild an app from the current directory (see 'acorn dev' to do this dynamically) + acorn run --update --name my-app . + + - Change an app's image + acorn run --update --image ghcr.io/acorn-io/hello-world:v1.0.2 --name my-app + +Automatic upgrades + - Automatic upgrade for an app will be enabled if '#', '*', or '**' appears in the image's tag. Tags will be sorted according to the rules for these special characters described below. The newest tag will be selected for upgrade. + '#' denotes a segment of the image tag that should be sorted numerically when finding the newest tag. + '*' denotes a segment of the image tag that should sorted alphabetically when finding the latest tag. + '**' denotes a wildcard. This segment of the image tag won't be considered when sorting. This is useful if your tags have a segment that is unpredictable. + + - Deploy the hello-world app with auto-upgrade enabled and matching all major, minor, and patch versions: + acorn run ghcr.io/acorn-io/hello-world:v#.#.# + +Publish Port Syntax + - Publish port 80 for any containers that define it as a port + acorn run -p 80 . + + - Publish container "myapp" using the hostname app.example.com + acorn run --publish app.example.com:myapp . + +Link Syntax + - Link the running acorn application named "mydatabase" into the current app, replacing the container named "db" + acorn run --link mydatabase:db . + +Secret Syntax +- Bind the acorn secret named "mycredentials" into the current app, replacing the secret named "creds" + acorn run --secret mycredentials:creds . + +Volume Syntax + - Create the volume named "mydata" with a size of 5 gigabyes and using the "fast" storage class + acorn run --volume mydata,size=5G,class=fast . + +- Bind the acorn volume named "mydata" into the current app, replacing the volume named "data" + acorn run --volume mydata:data . +``` + +### Options + +``` + --annotation strings Add annotations to the app and the resources it creates (format [type:][name:]key=value) (ex k=v, containers:k=v) + --args-file string Default args to apply to run/update command (default ".args.acorn") + --auto-upgrade Enabled automatic upgrades. + -b, --bidirectional-sync In interactive mode download changes in addition to uploading + --compute-class strings Set computeclass for a workload in the format of workload=computeclass. Specify a single computeclass to set all workloads. (ex foo=example-class or example-class) + --dangerous Automatically approve all privileges requested by the application + -i, --dev Enable interactive dev mode: build image, stream logs/status in the foreground and stop on exit + -e, --env strings Environment variables to set on running containers + --env-file string Default env vars to apply (default ".acorn.env") + -f, --file string Name of the build file (default "DIRECTORY/Acornfile") + -h, --help help for run + --interval string If configured for auto-upgrade, this is the time interval at which to check for new releases (ex: 1h, 5m) + -l, --label strings Add labels to the app and the resources it creates (format [type:][name:]key=value) (ex k=v, containers:k=v) + --link strings Link external app as a service in the current app (format app-name:container-name) + -m, --memory strings Set memory for a workload in the format of workload=memory. Only specify an amount to set all workloads. (ex foo=512Mi or 512Mi) + -n, --name string Name of app to create + --notify-upgrade If true and the app is configured for auto-upgrades, you will be notified in the CLI when an upgrade is available and must confirm it + -o, --output string Output API request without creating app (json, yaml) + -p, --publish strings Publish port of application (format [public:]private) (ex 81:80) + -P, --publish-all Publish all (true) or none (false) of the defined ports of application + -q, --quiet Do not print status + --region string Region in which to deploy the app, immutable + --replace Replace the app with only defined values, resetting undefined fields to default values + -s, --secret strings Bind an existing secret (format existing:sec-name) (ex: sec-name:app-secret) + -u, --update Update the app if it already exists + -v, --volume stringArray Bind an existing volume (format existing:vol-name,field=value) (ex: pvc-name:app-data) + --wait Wait for app to become ready before command exiting (default: true) +``` + +### Options inherited from parent commands + +``` + --config-file string Path of the acorn config file to use + --debug Enable debug logging + --debug-level int Debug log level (valid 0-9) (default 7) + --kubeconfig string Explicitly use kubeconfig file, overriding the default context + -j, --project string Project to work in +``` + +### SEE ALSO + +* [acorn](acorn.md) - + diff --git a/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_secret.md b/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_secret.md new file mode 100644 index 000000000..6e7b9e406 --- /dev/null +++ b/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_secret.md @@ -0,0 +1,46 @@ +--- +title: "acorn secret" +--- +## acorn secret + +Manage secrets + +``` +acorn secret [flags] [SECRET_NAME...] +``` + +### Examples + +``` + +acorn secret +``` + +### Options + +``` + -h, --help help for secret + -o, --output string Output format (json, yaml, {{gotemplate}}) + -q, --quiet Output only names +``` + +### Options inherited from parent commands + +``` + --config-file string Path of the acorn config file to use + --debug Enable debug logging + --debug-level int Debug log level (valid 0-9) (default 7) + --kubeconfig string Explicitly use kubeconfig file, overriding the default context + -j, --project string Project to work in +``` + +### SEE ALSO + +* [acorn](acorn.md) - +* [acorn secret create](acorn_secret_create.md) - Create a secret +* [acorn secret edit](acorn_secret_edit.md) - Edits a secret interactively +* [acorn secret encrypt](acorn_secret_encrypt.md) - Encrypt string information with clusters public key +* [acorn secret reveal](acorn_secret_reveal.md) - Manage secrets +* [acorn secret rm](acorn_secret_rm.md) - Delete a secret +* [acorn secret update](acorn_secret_update.md) - Update a secret + diff --git a/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_secret_create.md b/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_secret_create.md new file mode 100644 index 000000000..93dc1aae9 --- /dev/null +++ b/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_secret_create.md @@ -0,0 +1,52 @@ +--- +title: "acorn secret create" +--- +## acorn secret create + +Create a secret + +``` +acorn secret create [flags] SECRET_NAME +``` + +### Examples + +``` + +# Create secret with specific keys +acorn secret create --data key-name=value --data key-name2=value2 my-secret + +# Read full secret from a file. The file should have a type and data field. +acorn secret create --file secret.yaml my-secret + +# Read key value from a file +acorn secret create --data @key-name=secret.yaml my-secret +``` + +### Options + +``` + --data strings Secret data format key=value or @key=filename to read from file + --file string File to read for entire secret in aml/yaml/json format + -h, --help help for create + --replace Replace the secret with only defined values, resetting undefined fields to default values + --type string Secret type + -u, --update Update the secret if it already exists +``` + +### Options inherited from parent commands + +``` + --config-file string Path of the acorn config file to use + --debug Enable debug logging + --debug-level int Debug log level (valid 0-9) (default 7) + --kubeconfig string Explicitly use kubeconfig file, overriding the default context + -o, --output string Output format (json, yaml, {{gotemplate}}) + -j, --project string Project to work in + -q, --quiet Output only names +``` + +### SEE ALSO + +* [acorn secret](acorn_secret.md) - Manage secrets + diff --git a/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_secret_edit.md b/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_secret_edit.md new file mode 100644 index 000000000..47c523b2b --- /dev/null +++ b/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_secret_edit.md @@ -0,0 +1,39 @@ +--- +title: "acorn secret edit" +--- +## acorn secret edit + +Edits a secret interactively + +``` +acorn secret edit SECRET_NAME [flags] +``` + +### Examples + +``` +acorn secret edit my-secret +``` + +### Options + +``` + -h, --help help for edit +``` + +### Options inherited from parent commands + +``` + --config-file string Path of the acorn config file to use + --debug Enable debug logging + --debug-level int Debug log level (valid 0-9) (default 7) + --kubeconfig string Explicitly use kubeconfig file, overriding the default context + -o, --output string Output format (json, yaml, {{gotemplate}}) + -j, --project string Project to work in + -q, --quiet Output only names +``` + +### SEE ALSO + +* [acorn secret](acorn_secret.md) - Manage secrets + diff --git a/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_secret_encrypt.md b/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_secret_encrypt.md new file mode 100644 index 000000000..ec6fa5ba5 --- /dev/null +++ b/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_secret_encrypt.md @@ -0,0 +1,35 @@ +--- +title: "acorn secret encrypt" +--- +## acorn secret encrypt + +Encrypt string information with clusters public key + +``` +acorn secret encrypt [flags] STRING +``` + +### Options + +``` + -h, --help help for encrypt + --plaintext-stdin Take the plaintext from stdin + --public-key strings Pass one or more cluster publicKey values +``` + +### Options inherited from parent commands + +``` + --config-file string Path of the acorn config file to use + --debug Enable debug logging + --debug-level int Debug log level (valid 0-9) (default 7) + --kubeconfig string Explicitly use kubeconfig file, overriding the default context + -o, --output string Output format (json, yaml, {{gotemplate}}) + -j, --project string Project to work in + -q, --quiet Output only names +``` + +### SEE ALSO + +* [acorn secret](acorn_secret.md) - Manage secrets + diff --git a/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_secret_reveal.md b/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_secret_reveal.md new file mode 100644 index 000000000..7811545f7 --- /dev/null +++ b/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_secret_reveal.md @@ -0,0 +1,40 @@ +--- +title: "acorn secret reveal" +--- +## acorn secret reveal + +Manage secrets + +``` +acorn secret reveal [flags] [SECRET_NAME...] +``` + +### Examples + +``` + +acorn secret +``` + +### Options + +``` + -h, --help help for reveal + -o, --output string Output format (json, yaml, {{gotemplate}}) + -q, --quiet Output only names +``` + +### Options inherited from parent commands + +``` + --config-file string Path of the acorn config file to use + --debug Enable debug logging + --debug-level int Debug log level (valid 0-9) (default 7) + --kubeconfig string Explicitly use kubeconfig file, overriding the default context + -j, --project string Project to work in +``` + +### SEE ALSO + +* [acorn secret](acorn_secret.md) - Manage secrets + diff --git a/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_secret_rm.md b/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_secret_rm.md new file mode 100644 index 000000000..ebc7b2114 --- /dev/null +++ b/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_secret_rm.md @@ -0,0 +1,40 @@ +--- +title: "acorn secret rm" +--- +## acorn secret rm + +Delete a secret + +``` +acorn secret rm [SECRET_NAME...] [flags] +``` + +### Examples + +``` + +acorn secret rm my-secret +``` + +### Options + +``` + -h, --help help for rm +``` + +### Options inherited from parent commands + +``` + --config-file string Path of the acorn config file to use + --debug Enable debug logging + --debug-level int Debug log level (valid 0-9) (default 7) + --kubeconfig string Explicitly use kubeconfig file, overriding the default context + -o, --output string Output format (json, yaml, {{gotemplate}}) + -j, --project string Project to work in + -q, --quiet Output only names +``` + +### SEE ALSO + +* [acorn secret](acorn_secret.md) - Manage secrets + diff --git a/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_secret_update.md b/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_secret_update.md new file mode 100644 index 000000000..e07476a28 --- /dev/null +++ b/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_secret_update.md @@ -0,0 +1,50 @@ +--- +title: "acorn secret update" +--- +## acorn secret update + +Update a secret + +``` +acorn secret update [flags] SECRET_NAME +``` + +### Examples + +``` + +# Create secret with specific keys +acorn secret update --data key-name=value --data key-name2=value2 my-secret + +# Read full secret from a file. The file should have a type and data field. +acorn secret update --file secret.yaml my-secret + +# Read key value from a file +acorn secret update --data @key-name=secret.yaml my-secret +``` + +### Options + +``` + --data strings Secret data format key=value or @key=filename to read from file + --file string File to read for entire secret in aml/yaml/json format + -h, --help help for update + --type string Secret type +``` + +### Options inherited from parent commands + +``` + --config-file string Path of the acorn config file to use + --debug Enable debug logging + --debug-level int Debug log level (valid 0-9) (default 7) + --kubeconfig string Explicitly use kubeconfig file, overriding the default context + -o, --output string Output format (json, yaml, {{gotemplate}}) + -j, --project string Project to work in + -q, --quiet Output only names +``` + +### SEE ALSO + +* [acorn secret](acorn_secret.md) - Manage secrets + diff --git a/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_start.md b/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_start.md new file mode 100644 index 000000000..ce7a1577d --- /dev/null +++ b/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_start.md @@ -0,0 +1,40 @@ +--- +title: "acorn start" +--- +## acorn start + +Start an app + +``` +acorn start [flags] [ACORN_NAME...] +``` + +### Examples + +``` + +acorn start my-app + +acorn start my-app1 my-app2 +``` + +### Options + +``` + -h, --help help for start +``` + +### Options inherited from parent commands + +``` + --config-file string Path of the acorn config file to use + --debug Enable debug logging + --debug-level int Debug log level (valid 0-9) (default 7) + --kubeconfig string Explicitly use kubeconfig file, overriding the default context + -j, --project string Project to work in +``` + +### SEE ALSO + +* [acorn](acorn.md) - + diff --git a/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_stop.md b/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_stop.md new file mode 100644 index 000000000..5ecd9fb6c --- /dev/null +++ b/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_stop.md @@ -0,0 +1,40 @@ +--- +title: "acorn stop" +--- +## acorn stop + +Stop an app + +``` +acorn stop [flags] [ACORN_NAME...] +``` + +### Examples + +``` + +acorn stop my-app + +acorn stop my-app1 my-app2 +``` + +### Options + +``` + -h, --help help for stop +``` + +### Options inherited from parent commands + +``` + --config-file string Path of the acorn config file to use + --debug Enable debug logging + --debug-level int Debug log level (valid 0-9) (default 7) + --kubeconfig string Explicitly use kubeconfig file, overriding the default context + -j, --project string Project to work in +``` + +### SEE ALSO + +* [acorn](acorn.md) - + diff --git a/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_tag.md b/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_tag.md new file mode 100644 index 000000000..8bbedd86b --- /dev/null +++ b/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_tag.md @@ -0,0 +1,31 @@ +--- +title: "acorn tag" +--- +## acorn tag + +Tag an image + +``` +acorn tag [flags] SOURCE_IMAGE[:TAG] TARGET_IMAGE[:TAG] +``` + +### Options + +``` + -h, --help help for tag +``` + +### Options inherited from parent commands + +``` + --config-file string Path of the acorn config file to use + --debug Enable debug logging + --debug-level int Debug log level (valid 0-9) (default 7) + --kubeconfig string Explicitly use kubeconfig file, overriding the default context + -j, --project string Project to work in +``` + +### SEE ALSO + +* [acorn](acorn.md) - + diff --git a/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_uninstall.md b/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_uninstall.md new file mode 100644 index 000000000..08d35eeac --- /dev/null +++ b/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_uninstall.md @@ -0,0 +1,44 @@ +--- +title: "acorn uninstall" +--- +## acorn uninstall + +Uninstall acorn and associated resources + +``` +acorn uninstall [flags] +``` + +### Examples + +``` + +# Uninstall with confirmation +acorn uninstall + +# Force uninstall without confirmation +acorn uninstall -f +``` + +### Options + +``` + -a, --all Delete all volumes and secrets + -f, --force Do not prompt for confirmation + -h, --help help for uninstall +``` + +### Options inherited from parent commands + +``` + --config-file string Path of the acorn config file to use + --debug Enable debug logging + --debug-level int Debug log level (valid 0-9) (default 7) + --kubeconfig string Explicitly use kubeconfig file, overriding the default context + -j, --project string Project to work in +``` + +### SEE ALSO + +* [acorn](acorn.md) - + diff --git a/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_update.md b/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_update.md new file mode 100644 index 000000000..420e6afc1 --- /dev/null +++ b/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_update.md @@ -0,0 +1,69 @@ +--- +title: "acorn update" +--- +## acorn update + +Update a deployed Acorn + +``` +acorn update [flags] ACORN_NAME [deploy flags] +``` + +### Examples + +``` + + # Change the image on an Acorn called "my-app" + acorn update --image my-app + + # Change the image on an Acorn called "my-app" to the contents of the current directory (which must include an Acornfile) + acorn update --image . my-app + + # Enable auto-upgrade on an Acorn called "my-app" + acorn update --auto-upgrade my-app +``` + +### Options + +``` + --annotation strings Add annotations to the app and the resources it creates (format [type:][name:]key=value) (ex k=v, containers:k=v) + --args-file string Default args to apply to run/update command (default ".args.acorn") + --auto-upgrade Enabled automatic upgrades. + --compute-class strings Set computeclass for a workload in the format of workload=computeclass. Specify a single computeclass to set all workloads. (ex foo=example-class or example-class) + --confirm-upgrade When an auto-upgrade app is marked as having an upgrade available, pass this flag to confirm the upgrade. Used in conjunction with --notify-upgrade. + --dangerous Automatically approve all privileges requested by the application + -e, --env strings Environment variables to set on running containers + --env-file string Default env vars to apply to update command + -f, --file string Name of the build file (default "DIRECTORY/Acornfile") + -h, --help help for update + --image string Acorn image name + --interval string If configured for auto-upgrade, this is the time interval at which to check for new releases (ex: 1h, 5m) + -l, --label strings Add labels to the app and the resources it creates (format [type:][name:]key=value) (ex k=v, containers:k=v) + --link strings Link external app as a service in the current app (format app-name:container-name) + -m, --memory strings Set memory for a workload in the format of workload=memory. Only specify an amount to set all workloads. (ex foo=512Mi or 512Mi) + --notify-upgrade If true and the app is configured for auto-upgrades, you will be notified in the CLI when an upgrade is available and must confirm it + -o, --output string Output API request without creating app (json, yaml) + -p, --publish strings Publish port of application (format [public:]private) (ex 81:80) + -P, --publish-all Publish all (true) or none (false) of the defined ports of application + --pull Re-pull the app's image, which will cause the app to re-deploy if the image has changed + -q, --quiet Do not print status + --region string Region in which to deploy the app, immutable + -s, --secret strings Bind an existing secret (format existing:sec-name) (ex: sec-name:app-secret) + -v, --volume stringArray Bind an existing volume (format existing:vol-name,field=value) (ex: pvc-name:app-data) + --wait Wait for app to become ready before command exiting (default: true) +``` + +### Options inherited from parent commands + +``` + --config-file string Path of the acorn config file to use + --debug Enable debug logging + --debug-level int Debug log level (valid 0-9) (default 7) + --kubeconfig string Explicitly use kubeconfig file, overriding the default context + -j, --project string Project to work in +``` + +### SEE ALSO + +* [acorn](acorn.md) - + diff --git a/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_version.md b/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_version.md new file mode 100644 index 000000000..1806f8f07 --- /dev/null +++ b/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_version.md @@ -0,0 +1,37 @@ +--- +title: "acorn version" +--- +## acorn version + +Version information for acorn + +``` +acorn version [flags] +``` + +### Examples + +``` +acorn version +``` + +### Options + +``` + -h, --help help for version +``` + +### Options inherited from parent commands + +``` + --config-file string Path of the acorn config file to use + --debug Enable debug logging + --debug-level int Debug log level (valid 0-9) (default 7) + --kubeconfig string Explicitly use kubeconfig file, overriding the default context + -j, --project string Project to work in +``` + +### SEE ALSO + +* [acorn](acorn.md) - + diff --git a/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_volume.md b/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_volume.md new file mode 100644 index 000000000..88562f460 --- /dev/null +++ b/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_volume.md @@ -0,0 +1,41 @@ +--- +title: "acorn volume" +--- +## acorn volume + +Manage volumes + +``` +acorn volume [flags] [VOLUME_NAME...] +``` + +### Examples + +``` + +acorn volume +``` + +### Options + +``` + -h, --help help for volume + -o, --output string Output format (json, yaml, {{gotemplate}}) + -q, --quiet Output only names +``` + +### Options inherited from parent commands + +``` + --config-file string Path of the acorn config file to use + --debug Enable debug logging + --debug-level int Debug log level (valid 0-9) (default 7) + --kubeconfig string Explicitly use kubeconfig file, overriding the default context + -j, --project string Project to work in +``` + +### SEE ALSO + +* [acorn](acorn.md) - +* [acorn volume rm](acorn_volume_rm.md) - Delete a volume + diff --git a/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_volume_rm.md b/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_volume_rm.md new file mode 100644 index 000000000..d85857bfd --- /dev/null +++ b/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_volume_rm.md @@ -0,0 +1,39 @@ +--- +title: "acorn volume rm" +--- +## acorn volume rm + +Delete a volume + +``` +acorn volume rm [VOLUME_NAME...] [flags] +``` + +### Examples + +``` +acorn volume rm my-volume +``` + +### Options + +``` + -h, --help help for rm +``` + +### Options inherited from parent commands + +``` + --config-file string Path of the acorn config file to use + --debug Enable debug logging + --debug-level int Debug log level (valid 0-9) (default 7) + --kubeconfig string Explicitly use kubeconfig file, overriding the default context + -o, --output string Output format (json, yaml, {{gotemplate}}) + -j, --project string Project to work in + -q, --quiet Output only names +``` + +### SEE ALSO + +* [acorn volume](acorn_volume.md) - Manage volumes + diff --git a/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_wait.md b/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_wait.md new file mode 100644 index 000000000..9c76556b8 --- /dev/null +++ b/docs/versioned_docs/version-0.10/100-reference/01-command-line/acorn_wait.md @@ -0,0 +1,32 @@ +--- +title: "acorn wait" +--- +## acorn wait + +Wait an app to be ready then exit with status code 0 + +``` +acorn wait [flags] ACORN_NAME +``` + +### Options + +``` + -h, --help help for wait + -q, --quiet Do not print status +``` + +### Options inherited from parent commands + +``` + --config-file string Path of the acorn config file to use + --debug Enable debug logging + --debug-level int Debug log level (valid 0-9) (default 7) + --kubeconfig string Explicitly use kubeconfig file, overriding the default context + -j, --project string Project to work in +``` + +### SEE ALSO + +* [acorn](acorn.md) - + diff --git a/docs/versioned_docs/version-0.10/100-reference/_category_.yaml b/docs/versioned_docs/version-0.10/100-reference/_category_.yaml new file mode 100644 index 000000000..5f5466532 --- /dev/null +++ b/docs/versioned_docs/version-0.10/100-reference/_category_.yaml @@ -0,0 +1 @@ +label: Reference diff --git a/docs/versioned_docs/version-0.10/110-faq.md b/docs/versioned_docs/version-0.10/110-faq.md new file mode 100644 index 000000000..491a70232 --- /dev/null +++ b/docs/versioned_docs/version-0.10/110-faq.md @@ -0,0 +1,86 @@ +--- +title: FAQ +--- + +### Where can I get help? + +There are several ways you can get help from the community and Acorn's maintainers: + +- For bugs or feature requests, open an issue [here](https://github.com/acorn-io/runtime/issues/new) +- For questions or discussions, visit our [forum](https://github.com/acorn-io/runtime/discussions) +- To reach out to and interact with the rest of the community, [join our Slack](https://slack.acorn.io) + +### How can I report a security issue? + +Please see our [security docs](/architecture/security-considerations). + +### How can I troubleshoot issues with the Acorn control plane? + +First, check that the Acorn control plane pods are running on the cluster. Using a tool like `kubectl` you can run: + +```bash +kubectl get deploy -n acorn-system +``` + +To gather more information, you can view the Acorn control plane logs by running: + +```bash +kubectl logs -n acorn-system -f -l app=acorn-api + +- and - + +kubectl logs -n acorn-system -f -l app=acorn-controller +``` + +#### Does Acorn support CustomResourceDefinitions (CRDs)? + +CRD support is a commonly requested feature and we are thinking hard about how and whether we can support this. We recognize CRDs' value and prominence in the Kubernetes ecosystem, but because every CRD has its own unique impact and lifecycle, Acorn cannot reliably and predictably manage CustomResources generically. We are investigating different approaches and solutions. + +If you have a specific CRD use-case, please share it [here](https://github.com/acorn-io/runtime/issues/329). + +#### What is an Acorn image? Are you bundling and duplicating the container images I reference in my Acornfile? + +Acorn images leverage existing container image standards and functionality. A normal [OCI container image](https://github.com/opencontainers/image-spec/blob/main/spec.md) is a collection of layers stored in a OCI registry and linked together with an image manifest. An Acorn image is just that as well. It is an OCI index that has references to the Acorn metadata manifest and existing container image manifests. Its manifest references existing image manifests in the registry by digest. + +There is no duplication of content in the registry as all the existing image digests do not change (by design). The only time content is duplicated is if a referenced image is in a different OCI registry than the one you are pushing the Acorn to. This is by design and viewed as a feature. This keeps all content specific to your app in one registry so that you don't have to deal with multiple registry auth and proxy issue at deployment. Also this model ensures your app will stay fully intact even if an image is deleted or a tag is changed. + +#### I deployed an Acorn app and the endpoint says "pending". What's broken? + +If the endpoint is HTTP/HTTPS, you either don't have an ingress controller or it isn't set up properly. If you are sure your ingress controller is functioning properly, it may not be set as the default for your cluster and you need to tell Acorn to use it as part of the install command: + +```shell +acorn install --ingress-class-name nginx +``` + +"nginx" is just an example in this case. Your actual ingress class name may vary. + +If the endpoint is non-HTTP, like TCP, your cluster needs the ability to support [services of type LoadBalancer](https://kubernetes.io/docs/concepts/services-networking/service/#loadbalancer). + +#### I am hitting rate limits from DockerHub + +If you are experiencing rate limiting issues from DockerHub, you can log in to your account to increase the number of requests. + +```yaml +apiVersion: v1 +kind: Secret +metadata: + name: index.docker.io + labels: + acorn.io/credential: "true" +type: acorn.io/credential +data: + username: # base64-encoded username + password: # base64-encoded password + serverAddress: # base64-encoded "index.docker.io" +``` + +```shell +#apply yaml to the acorn-image-system namespace +kubectl apply -f dockersecret.yaml -n acorn-image-system + +#verify secret was created +kubectl get secrets -n acorn-image-system + +#acorn build/push/pull will now use these credentials +``` + diff --git a/docs/versioned_docs/version-0.10/30-installation/01-installing.md b/docs/versioned_docs/version-0.10/30-installation/01-installing.md new file mode 100644 index 000000000..21bbdea8d --- /dev/null +++ b/docs/versioned_docs/version-0.10/30-installation/01-installing.md @@ -0,0 +1,192 @@ +--- +title: Installing +--- + + +To install Acorn, you will need the Acorn CLI and a Kubernetes cluster. Follow one of the methods below to install the Acorn CLI and then install onto the [Kubernetes cluster](#installing-acorn-onto-kubernetes-clusters). + +```shell +acorn install +``` + +In many cases, the default installation options for Acorn are sufficient, but there are a number of options you can use to customize Acorn. See our [Installation Options](30-installation/02-options.md) page for more details. + +## Acorn CLI + +### Homebrew (macOS & Linux) + +The preferred method for installing on Mac and Linux is to use the brew package manager. + +You can install the latest Acorn CLI with the following: + +```shell +brew install acorn-io/cli/acorn +``` + +You can also follow the binary installation below. + +### curl|sh install (macOS & Linux) + +If you don't have homebrew, you can install the CLI with this one-liner: + +```shell +curl https://get.acorn.io | sh +``` + +### Scoop (Windows) + +You can install the latest Acorn CLI with the following: + +```shell +scoop install acorn +``` + +### Manual install + +You can download the Acorn CLI binary from the project's [GitHub page](https://github.com/acorn-io/runtime/releases). + +Download the correct binary for your platform. + +#### macOS + +Download either the universal DMG or the tar.gz file. + +For the DMG run through the installer. + +For the tar.gz download: + +```shell +tar -zxvf ~/Downloads/acorn-v-macos-universal.tar.gz +cp ~/Downloads/acorn /usr/local/bin/acorn +``` + + *Note: if using zsh you will need to make sure ulimit -f can handle files > 140MB* + +#### Linux + +Download the tar.gz archive for your architecture. Uncompress and move the binary to your PATH. + +```shell + tar -zxvf ~/Downloads/acorn-v-linux-.tar.gz + mv ~/Downloads/acorn /usr/local/bin +``` + +#### Windows + +Uncompress and move the binary to your PATH. + +#### Development Binaries (main build) + +The last successful build from the HEAD of the main branch is available for +[macOS](https://cdn.acrn.io/cli/mac_darwin_all/acorn), +[Linux](https://cdn.acrn.io/cli/default_linux_amd64_v1/acorn), and +[Windows](https://cdn.acrn.io/cli/default_windows_amd64_v1/acorn.exe) + +### Shell completion + +The Acorn CLI supports command autocompletion. If you installed acorn using homebrew, this is already configured for you. If you installed using the manual or curl|sh method, you must enable shell completion yourself. + +To set autocompletion for the current terminal session, use the command that matches your shell: + +```shell +source <(acorn completion bash) +source <(acorn completion zsh) +acorn completion fish | source +``` + +For permanent effect add the same line to your shell specific profile: + +- ~/.bashrc +- ~/.zshrc +- ~/.config/fish/config.fish + +## Installing Acorn onto Kubernetes clusters + +Acorn will need to be initialized on each Kubernetes cluster you plan to use it on. + +```shell +acorn install +``` + +Acorn can install onto any type of Kubernetes cluster capable of running normal workloads. The following are requirements and considerations for installing Acorn. + +### Cluster Requirements +#### Kubernetes version + +Acorn requires Kubernetes 1.23 or greater. + +#### Privileges + +You must have cluster admin privileges to install Acorn. See our [RBAC documentation](60-architecture/02-security-considerations.md#rbac) for more details. + +#### Ingress and Service LoadBalancers + +Acorn can publish your applications as publicly accessible endpoints. + +For this to work, your Kubernetes cluster must have an [ingress controller](https://kubernetes.io/docs/concepts/services-networking/ingress-controllers/) for HTTP endpoints and means for fulfilling [services of type LoadBalancer](https://kubernetes.io/docs/concepts/services-networking/service/#loadbalancer) for non-HTTP endpoints, such as TCP endpoints. + +:::info +When running on Google Kubenertes Engine, it is necessary to toggle on [--publish-builders](100-reference/01-command-line/acorn_install.md#options). This makes the builders for Acorn available through ingress which is necessary for the GKE runtime. +::: + +#### Storage + +Acorn supports persistent storage through the use of volumes. For this to work, your Kubernetes cluster must have a [default storage class](https://kubernetes.io/docs/concepts/storage/storage-classes/). + +### YAML Based Install + +If you would like to see the generated objects prior to installing to your Kubernetes cluster run: + +```shell +acorn install -o yaml > install.yaml +``` + +This will generate the Kubernetes objects yaml files and write them to `install.yaml` which can then be installed to your cluster using: + +```shell +kubectl apply -f install.yaml +``` +### Local Development Clusters + +For local development, Acorn has been tested with Rancher Desktop, Docker Desktop, and Minikube. If you are using one of these systems, please consider the following: + +**Rancher Desktop** comes with a working ingress controller, service loadbalancer solution, and storage class by default. No additional configuration is necessary. + +**Docker Desktop** comes with a storage class and service loadbalancer solution, but not an ingress. If you're using Docker Desktop and don't have one installed, Acorn will install the [Traefik v2 Ingress Controller](https://doc.traefik.io/traefik/v2.8/providers/kubernetes-ingress/) for you. + +**Minikube** comes with a default storage class, but requires that you [enable ingress explicitly](https://kubernetes.io/docs/tasks/access-application-cluster/ingress-minikube/#enable-the-ingress-controller) with the following command: + +```shell +minikube addons enable ingress +``` + +It's not obvious in the above minikube documentation, but after enabling ingress, if you want to access your applications locally, you must also run: + +```shell +minikube tunnel +``` + +The tunnel command also services as the service loadbalancer solution. If it is running, your TCP services will be published to `localhost`. + +**K3d** comes with a working ingress controller, service loadbalancer solution, and storage class by default. However, when creating your K3d cluster, you must configure it to proxy traffic from localhost to the cluster, so that endpoints resolve properly: + +```shell +k3d cluster create --api-port 6550 -p "80:80@loadbalancer" +``` + +If you choose to use a port other than `80` like so: + +```shell +k3d cluster create --api-port 6550 -p "8081:80@loadbalancer" +``` + +then you must reflect that in the `acorn install` command by specifying the port with the `--cluster-domain` flag: + +```shell +acorn install --cluster-domain '.local.oss-acorn.io:8081' +``` + +**Kind** comes with a working storage class by default, but you need to take some extra steps to get ingress and service loadbalancer capabilities: + +- For ingress, you need to configure the `kind` cluster with a host port mapping and then deploy an ingress controller. You can find more details in the [official documentation](https://kind.sigs.k8s.io/docs/user/ingress/). +- For service loadbalancer capabilities, the [`kind` docs](https://kind.sigs.k8s.io/docs/user/loadbalancer/) recommend to deploy [MetalLB](https://metallb.universe.tf/). diff --git a/docs/versioned_docs/version-0.10/30-installation/02-options.md b/docs/versioned_docs/version-0.10/30-installation/02-options.md new file mode 100644 index 000000000..239a9b335 --- /dev/null +++ b/docs/versioned_docs/version-0.10/30-installation/02-options.md @@ -0,0 +1,167 @@ +--- +title: Options +--- + +## Acorn image + +When you install acorn, it will launch several workloads in your cluster, including an api-server and controller. By default, these workloads will use the `ghcr.io/acorn-io/runtime` image. You can customize this image by setting the `--image` option. This is useful if you are installing acorn in an environment where you are required to pull images from a private registry. + +## TLS via Let's Encrypt + +When you launch an acorn and it has published ports, acorn will generate a unique URL for accessing it, like so: + +```bash +$ acorn run -P ghcr.io/acorn-io/hello-world + +$ acorn ps +NAME IMAGE COMMIT HEALTHY UP-TO-DATE CREATED ENDPOINTS MESSAGE +little-snowflake ghcr.io/acorn-io/hello-world eab5f8c77bd6 1 1 6m2s ago https://webapp-little-snowflake-2b3b4c8d.3gjv35.dev-on-acorn.io => webapp:80 OK +``` + +By default, endpoints are `http`. To have acorn automatically generate a [Let's Encrypt](https://letsencrypt.org/) certificate and secure your endpoints, you can enable acorn's Let's Encrypt integration like this: + +```bash +acorn install --lets-encrypt enabled +``` + +If you add this flag, you'll be prompted during install to agree to Let's Encrypt's [Terms of Service](https://letsencrypt.org/documents/LE-SA-v1.3-September-21-2022.pdf) and supply an email. You can supply these as flags too: + +```bash +acorn install --lets-encrypt enabled --lets-encrypt-tos-agree=true --lets-encrypt-email +``` + +:::info +Let's Encrypt integration is only useful if you are running a non-local Kubernetes cluster. If you are running acorn on a local cluster such as Docker Desktop, Rancher Desktop, or minikube, enabling Let's Encrypt will have no effect. We don't issue certificates for the `.local.oss-acorn.io` domains that are used in this scenario. +::: + +## Endpoint domain names + +Acorn provides several installation options for controlling the domain name used to generate endpoints. These are outlined in detail on our [network publishing](https://docs.acorn.io/production/publish-http) page. + +## Custom CA bundle + +Acorn allows a user to provide a custom certificate authority (CA) bundle so that users can add their own private CA that acorn will trust. The most common use case is for acorn to trust an internal image registry that is signed by a private CA. + +To do so, you will need to go through the following steps: + +1. Provide your CA certificate chain in the following secret. + +```bash +kubectl -n acorn-image-system create secret generic cabundle --from-file=ca-certificates.crt=/path/to/your/ca-certificates.crt + +kubectl -n acorn-system create secret generic cabundle --from-file=ca-certificates.crt=/path/to/your/ca-certificates.crt +``` + +:::info +You must provide the **full** CA certificate chain as it will override existing CA certificates in acorn control plane. +::: + +2. Install acorn with the following option + +```bash +acorn install --use-custom-ca-bundle +``` + +## Ingress class name + +Acorn [requires an ingress controller](30-installation/01-installing.md#ingress-and-service-loadbalancers) to function properly. If your cluster has more than one ingress controller or if it has one but it isn't set as the [default](https://kubernetes.io/docs/concepts/services-networking/ingress/#default-ingress-class), you can explicitly set the ingress class using `--ingress-class-name`. + +## Memory + +There are two `install` flags for interacting memory: `--workload-memory-default` and `--workload-memory-maximum`. Their values can both be viewed by running `acorn info`. + +Check out our page on [sizing](https://docs.acorn.io/production/acorn-sizing) for more information. + +### --workload-memory-default + +This flag is responsible for setting the memory amount that will get defaulted to should no other value be found. + +```console +acorn install --workload-memory-default 512Mi +``` + +Running the above will set all Acorns on the cluster (current and future) to use `512Mi` as their default memory. + +### --workload-memory-maximum + +This flag sets a maximum that when exceeded prevents the offending Acorn from being installed. + +```console +acorn install --workload-memory-maximum 1Gi +``` + +This will set it so all Acorns on this cluster will be unable to install should they exceed `1Gi` of memory. + +## Ignoring user-defined labels and annotations + +There are situations where you may not want a user to be able to label or annotate the objects created by Acorn in the workload cluster. For such circumstances, the installation flag `--ignore-user-labels-and-annotations` exists. If this flag is passed to `acorn install`, then, except for the metadata scope, labels and annotations defined by users in their Acorns will be ignored when creating objects. No error nor warning will be produced. + +If this is too restrictive, and you would like to allow certain user-defined labels and annotations to propagate to the Kubernetes objects then you can use the `--allow-user-label` and `allow-user-annotation` installation flags. These flags take a comma-delimited list of label/annotation keys that are allowed to propagate. You can also specify the flags multiple times and the values will be concatenated to create the final list. If the `--ignore-user-labels-and-annotations` is not supplied or is false, then these flags have no effect. + +Note that in order to allow propagation of user-defined labels and annotations on an Acorn installation that previous disallowed it, one must pass `--ignore-user-labels-and-annotations=false` to `acorn install`. + +## Manually managing volume classes + +The default installation of Acorn will automatically create and sync any storage classes in the cluster to volume classes. That means that when a storage class is created or deleted, the corresponding volume class will also be created or deleted. Additionally, the default storage class in the cluster will also become the default volume class. An admin could edit these generated volume classes to set the fields on them (like min/max/default size) and those updates will be maintained. These generated volume classes will be available to every user in the cluster. + +If an admin would rather manually manage the volume classes and not have these generated ones, then the `--manage-volume-classes` installation flag is available. The generated volume classes are not generated if this flag is used, and are deleted when the flag is set on an existing Acorn installation. If the flag is again switched off with `--manage-volume-classes=false`, then the volume classes will be generated again. + +## Kubernetes NetworkPolicies + +Acorn can automatically create and manage Kubernetes [NetworkPolicies](https://kubernetes.io/docs/concepts/services-networking/network-policies/) to isolate Acorn projects on the network level. +This behavior can be enabled by passing `--network-policies=true` to `acorn install`, and can later be disabled by passing `--network-policies=false`. + +When NetworkPolicies are enabled, Acorn workloads that publish ports that use HTTP will be allowed to receive traffic from internal (other pods in the cluster) and external (through the cluster's ingress) sources. +To secure this further, you can require all traffic to Acorn workloads flow through your ingress by specifying the `--ingress-controller-namespace` parameter during installation. + +:::caution +Acorn workloads that publish ports that use TCP will be allowed to receive traffic from any source, whether it comes from outside or inside of the cluster. +::: + +To allow traffic from a specific namespace to all Acorn apps in the cluster, use `--allow-traffic-from-namespace=`. +This is useful if there is a monitoring namespace, for example, that needs to be able to connect to all the pods created by Acorn in order to scrape metrics. + +## Working with external LoadBalancer controllers + +If you are using an external `LoadBalancer` controller that requires annotations on `LoadBalancer` Services to operate, such as the `aws-load-balancer-controller`, you can pass the `--service-lb-annotation` flag to `acorn install`. This will cause Acorn to add the specified annotations to all `LoadBalancer` Services it creates. The value of the flag should be a comma-separated list of key-value pairs, where the key is the annotation name and the value is the annotation value. For example: + +```bash +acorn install --service-lb-annotation service.beta.kubernetes.io/aws-load-balancer-type=external,service.beta.kubernetes.io/aws-load-balancer-scheme=internet-facing,service.beta.kubernetes.io/aws-load-balancer-nlb-target-type=instance +``` + +For readability, you can also pass the flag multiple times, and the values will be concatenated. For example: + +```bash +acorn install \ + --service-lb-annotation service.beta.kubernetes.io/aws-load-balancer-type=external \ + --service-lb-annotation service.beta.kubernetes.io/aws-load-balancer-scheme=internet-facing \ + --service-lb-annotation service.beta.kubernetes.io/aws-load-balancer-nlb-target-type=instance \ +``` + +Lastly, you can unset the annotations defined by the `--service-lb-annotation` flag by passing an empty string to the flag. For example: + +```bash +acorn install --service-lb-annotation "" +``` + +:::note +These annotations get added before the the `LoadBalancer` Service is created which is a requisite for some `LoadBalancer` controllers to work properly, like the `aws-load-balancer-controller`. +::: + +## Changing install options + +If you want to change your installation options after the initial installation, just rerun `acorn install` with the new options. This will update the existing install dynamically. + +For strings array flags, you can reset the slice to empty by pass empty string "". For example: + +```bash +acorn install --propagate-project-annotation "" +``` + +## Install Profiles + +When you are installing Acorn, you can specify a profile to use. A profile is a set of installation flag defaults that are pre-defined. You can see the list of available profiles by running `acorn install --help`. The default profile is `default`, and it is used if no profile is specified. + +:::note +Once a profile is set, this will set new default values based on the profile. Any default values previously used will be switched to the new profile defaults. However, any install flags that were or are specified will still be respected. +::: diff --git a/docs/versioned_docs/version-0.10/30-installation/03-upgrading.md b/docs/versioned_docs/version-0.10/30-installation/03-upgrading.md new file mode 100644 index 000000000..6e2fa0bc8 --- /dev/null +++ b/docs/versioned_docs/version-0.10/30-installation/03-upgrading.md @@ -0,0 +1,28 @@ +--- +title: Upgrades +--- + +## CLI + +In order to upgrade Acorn on a Kubernetes cluster you must first download an updated Acorn CLI version. + +### Brew + +```shell +brew update +brew upgrade acorn-io/cli/acorn +``` + +### Binary + +Download the latest binary version and install following the binary install method. + +## Upgrading Acorn on a Kubernetes cluster + +Once a new version of Acorn is being used the Acorn version on a Kubernetes cluster will also need to be updated. You can run the following command to do the upgrade: + +```shell +acorn install +``` + +This will download the newest versions of the Acorn components for the cluster. diff --git a/docs/versioned_docs/version-0.10/30-installation/100-uninstalling.md b/docs/versioned_docs/version-0.10/30-installation/100-uninstalling.md new file mode 100644 index 000000000..47f0a9865 --- /dev/null +++ b/docs/versioned_docs/version-0.10/30-installation/100-uninstalling.md @@ -0,0 +1,29 @@ +--- +title: Uninstalling +--- + +The following command will uninstall the Acorn components along with the Acorn apps deployed by Acorn. When you run the command you will be shown the components that will be removed and remain. + +```shell +acorn uninstall +#Action | Namespace | Name | Kind | API Version +#keep | | acorn | Namespace | v1 +#delete | | acorn-system | Namespace | v1 +#delete | | acorn-system | ClusterRole | rbac.authorization.k8s.io/v1 +#delete | | acorn-system | ClusterRoleBinding | rbac.authorization.k8s.io/v1 +#delete | | appinstances.internal.acorn.io | CustomResourceDefinition | apiextensions.k8s.io/v1 +#delete | | crimson-darkness-ef125bc3-145 | Namespace | v1 +#delete | | v1.api.acorn.io | APIService | apiregistration.k8s.io/v1 +#delete | acorn-system | acorn-api | Deployment | apps/v1 +#delete | acorn-system | acorn-api | Service | v1 +#delete | acorn-system | acorn-config | ConfigMap | v1 +#delete | acorn-system | acorn-controller | Deployment | apps/v1 +#delete | acorn-system | acorn-dns | Secret | v1 +#delete | acorn-system | acorn-system | ServiceAccount | v1 +#delete | crimson-darkness-ef125bc3-145 | default-pull-ef125bc3-145 | Secret | v1 +#? Do you want to delete/keep the above resources? To delete all resources pass run "acorn uninstall --all" (y/N) +``` + +Once confirmed Acorn will remove the listed components. + +If you would like to delete all resources you can add the `--all` flag to remove resources that normal uninstall would leave behind. diff --git a/docs/versioned_docs/version-0.10/30-installation/_category_.yaml b/docs/versioned_docs/version-0.10/30-installation/_category_.yaml new file mode 100644 index 000000000..f8e427f38 --- /dev/null +++ b/docs/versioned_docs/version-0.10/30-installation/_category_.yaml @@ -0,0 +1 @@ +label: Installation diff --git a/docs/versioned_docs/version-0.10/37-getting-started.md b/docs/versioned_docs/version-0.10/37-getting-started.md new file mode 100644 index 000000000..f2360ca3a --- /dev/null +++ b/docs/versioned_docs/version-0.10/37-getting-started.md @@ -0,0 +1,416 @@ +--- +title: Getting Started +--- + +:::note +This getting started guide is to walk through using runtime on your own Kubernetes clusters. To get started quickly with Acorn without needing a Kubernetes cluster, check out the [getting started guide] (https://docs.acorn.io/getting-started) for our hosted offering. +::: + +In this walk through you will build a Python web app, package it up and deploy it as an Acorn app. +The app will interact with Redis and Postgres, which both will be packaged along with the web app in a single Acorn image. + +> The guide makes use of Python, Redis and Postgres here, but you don't need to be familiar with those technologies, as the examples should be understandable without preliminary knowledge in those. + +## Prerequisites + +To run this example, you will need to have the Acorn CLI installed and administrative access to a Kubernetes cluster. +Here you can find some documentation on how to get there: + +- [Acorn CLI](30-installation/01-installing.md) +- Access to a Kubernetes cluster through `kubectl` from your CLI. Some great options for local development are [Rancher Desktop](https://docs.rancherdesktop.io/getting-started/installation), [K3s](https://rancher.com/docs/k3s/latest/en/quick-start/), [k3d](https://k3d.io/v5.4.4/#installation), or [Docker Desktop](https://www.docker.com/get-started/). It also works with any other Kubernetes distribution, for example a managed instance hosted in a major cloud provider or a cluster provided by your work environment. + +## Step 1. Prepare the cluster + +Installing the Acorn server-side components into your cluster is as easy as running + +```bash +acorn install +``` + +> Note: Installing Acorn into a Kubernetes cluster requires cluster-admin privileges. Please see our [architecture overview](60-architecture/01-ten-thousand-foot-view.md) to learn what components will be deployed. + +## Step 2. Create your app + +Let's start by creating a few files that compose our Python web app. You can also find all these files in the `docs/flask` directory of the [examples](https://github.com/acorn-io/examples) GitHub repo if you'd rather start from there. + +```shell +# Create a directory structure for our web app +mkdir acorn-test-app + +# Change into the root of the new directory tree +cd acorn-test-app +``` + +### The Web App + +Now create the basic Python web app in a file called `app.py`, which stores a visitor count in the Redis Cache and fetches a list of items from a Postgres Database. + +```python title="acorn-test-app/app.py" +import logging as log +import os + +import psycopg2 +import redis +from flask import Flask, render_template_string + +# HTML Jinja2 Template which will be shown in the browser +page_template = ''' +
+

{{ welcome_text }}


+ You're visitor #{{ visitors }} to learn what squirrels love the most:
+
    + {%- for food in foods %} +
  • {{ food }}
    • + {%- endfor %} +
+
+ ''' + +# Defining the Flask Web App +app = Flask(__name__) +cache = redis.StrictRedis(host='cache', port=6379) + + +# The website root will show the page_template rendered with +# - visitor count fetched from Redis Cache +# - list of food fetched from Postgres DB +# - welcome text passed in as environment variable +@app.route('/') +def root(): + visitors = cache_get_visitor_count() + food = db_get_squirrel_food() + + return render_template_string(page_template, visitors=visitors, foods=food, welcome_text=os.getenv("WELCOME", "Hey Acorn user!")) + + +# Fetch the squirrel food from the Postgres database +def db_get_squirrel_food(): + conn = psycopg2.connect( + host="db", + database="acorn", + user=os.environ['PG_USER'], + password=os.environ['PG_PASS'], + ) + + cur = conn.cursor() + cur.execute("SELECT food FROM squirrel_food;") + + return [x[0] for x in cur.fetchall()] # Return the list of food items + + +# Increment the visitor count in the Redis cache and return the new value +def cache_get_visitor_count(): + return cache.incr('visitors') +``` + +### Python Requirements + +Alongside the Python code, we need the list of dependencies to install. Save the following in the file `requirements.txt`: + +```txt title="acorn-test-app/requirements.txt" +flask +psycopg2-binary +redis +``` + +### Dockerfile + +Now we have all the code and want to bundle it up in a Docker container. +Create the `Dockerfile` with the following content: + +```docker title="acorn-test-app/Dockerfile" +FROM python:3-alpine +WORKDIR /app +ENV FLASK_APP=app.py +ENV FLASK_RUN_HOST=0.0.0.0 +RUN apk add --no-cache gcc musl-dev linux-headers +ADD requirements.txt . +RUN pip install -r requirements.txt +COPY . . +EXPOSE 5000 +CMD ["flask", "run"] +``` + +## Step 3. Author your Acornfile + +Create your Acornfile with the following contents. Each item will be explained below, this file demonstrates a lot of what Acorn can do. + +```acorn title="acorn-test-app/Acornfile" +args: { + // Configure your personal welcome text + welcome: "Hello Acorn User!!" +} + +containers: { + app: { + build: "." + env: { + "PG_USER": "postgres" + "PG_PASS": "secret://quickstart-pg-pass/token" + "WELCOME": args.welcome + if args.dev { "FLASK_ENV": "development" } + } + dependsOn: [ + "db", + "cache" + ] + if args.dev { dirs: "/app": "./" } + ports: publish: "5000/http" + } + cache: { + image: "redis:alpine" + ports: "6379/tcp" + } + db: { + image: "postgres:alpine" + env: { + "POSTGRES_DB": "acorn" + "POSTGRES_PASSWORD": "secret://quickstart-pg-pass/token" + } + dirs: { + if !args.dev { + "/var/lib/postgresql/data": "volume://pgdata?subpath=data" + } + } + files: { + "/docker-entrypoint-initdb.d/00-init.sql": "CREATE TABLE squirrel_food (food text);" + "/docker-entrypoint-initdb.d/01-food.sql": std.join([for food in localData.food {"INSERT INTO squirrel_food VALUES ('\(food)');"}], "\n") + } + ports: "5432/tcp" + } +} + +localData: { + food: [ + "acorns", + "hazelnuts", + "walnuts" + ] +} + +volumes: { + if !args.dev { + "pgdata": { + accessModes: "readWriteOnce" + } + } +} + +secrets: { + "quickstart-pg-pass": { + type: "token" + } +} +``` + +### Explaining the Acornfile + +- `args` section: describes a set of arguments that can be passed in by the user of this Acorn image + - A help text will be auto-generated using the comment just above the arg: + + ```bash + $ acorn run . --help + Usage of Acornfile: + --welcome string Configure your personal welcome text + ``` + +- `containers` section: describes the set of containers your Acorn app consists of + - Note: `app`, `db` and `cache` are custom names of your containers + - `app` - Our Python Flask App + - `build`: build from Dockerfile that we created + - `env`: environment variables, statically defined, referencing a secret or referencing an Acorn argument + - `dependsOn`: dependencies that have to be up and running before the app is started (here it is waiting for the database and the cache to be running) + - `ports`: using the `publish` type, we expose the app inside the cluster but also outside of it using an auto-generated ingress resource ([more on this later](#step-5-access-your-app)) + - `dirs`: Directories to mount into the container filesystem + - `if !args.dev`: The following block applies only if built-in development mode is **disabled**. ([more on the development mode later](#step-6-development-mode)) + - `dirs: "/app": "./"`: Mount the current directory to the /app dir, which is where the code resides inside the container as per the `Dockerfile`. This is to enable hot-reloading of code. + - `cache` - Redis + - `image`: existing OCI/Docker image to use (here: from DockerHub library) + - `ports`: no type defined, defaults to `internal`, which makes it available to the other containers in this Acorn app + - `db` - Postgres Database Server + - `image`, `env`,`ports`: nothing new here + - `dirs`: Directories to mount into the container filesystem + - `if !args.dev`: The following block applies only if the built-in development mode is **disabled** ([more on the development mode later](#step-6-development-mode)) + - `volume://pgdata?subpath=data`: references a volume defined in the top-level `volumes` section in the Acornfile and specifies the subpath `data` as the mountpoint. + - `files`: Similar to `dirs` but only for files. Additionally, content can be created in-line and even utilize generating functions. +- `localData`: Set of variables for this Acorn app + - `food`: Custom variable, defining a list of food which is accessed in `containers.db.files` to pre-fill the database. +- `volumes`: (persistent) data volumes to be used by any container in the Acorn app + - `pgdata` custom volume name, referenced in `containers.db.dirs` + - `accessModes`: (list of) modes to allow access to this volume +- `secrets`: set of secrets that can be auto-generated and used by any container in the Acorn app + - `quickstart-pg-pass`: custom secret name, referenced by `containers.app.env` and `containers.db.env` + - `type`: There are several [secret types](https://docs.acorn.io/authoring/secrets#types-of-secrets). Here, a token (random string) will be generated for you at runtime. + +## Step 4. Run your Acorn app + +To start your Acorn app just run: + +```bash +acorn run -n awesome-acorn . +``` + +or customize the welcome text argument via: + +```bash +acorn run -n awesome-acorn . --welcome "Let's Get Started" +``` + +The `-n awesome-acorn` gives this app a specific name so that the rest of the steps can refer to it. If you omit `-n`, a random two-word name will be generated. + +## Step 5. Access your app + +Due to the configuration `ports: publish: "5000/http"` under `containers.app`, our web app will be exposed outside of our Kubernetes cluster using the cluster's ingress controller. +Checkout the running apps via + +```bash +acorn apps +``` + +```bash +$ acorn apps +NAME IMAGE HEALTHY UP-TO-DATE CREATED ENDPOINTS MESSAGE +awesome-acorn 2d73c8a0493f 3 3 121m ago http://app-awesome-acorn-56d50c8c0915.local.oss-acorn.io => app:5000 OK +``` + +You probably already noticed the link right there in the `ENDPOINTS` column. It will take you to your Python Flask App. + +## Step 6. Development Mode + +Now that we have a way to package and deploy our app, lets look at how we can configure the Acornfile to enable the development flow. In this mode, we will be able to make changes and see them updated inside the app container in real time. + +To enable the Acorn development mode, first stop the app and then re-run with the `dev` command. + +```bash +acorn stop awesome-acorn +acorn dev -n awesome-acorn +``` + +In development mode, Acorn will watch the local directory for changes and synchronize them to the running Acorn app. +In general, changes to the Acornfile are directly synchronized, e.g. adding environment variables, etc. +Depending on the change, the deployed containers will be recreated. + +The following lines additionally enable hot-reloading of code by mounting the current local directory into the app container: + +```acorn +containers: { + app: { + // ... + if args.dev { dirs: "/app": "./" } + //... + } + //... +} +``` + +In this case, additionally `if args.dev { "FLASK_ENV": "development" }` enables Flask's development mode. + +Running in development mode, Acorn will keep a session open, streaming all the container logs to your terminal and notifying you of any changes that are happening. Press `Ctrl-c` to end the session and terminate the running app. + +To test it, you can change something in the `app.py`. +For example, add a line to the HTML template at the top and change it to + +```python +# HTML Jinja2 Template which will be shown in the browser +page_template = ''' +
+

{{ welcome_text }}


+

This is a change :)

+ You're visitor #{{ visitors }} to learn what squirrels love the most:
+
    + {%- for food in foods %} +
  • {{ food }}
    • + {%- endfor %} +
+
+ ''' +``` + +You will see the change applied when you reload the application's page in your browser. + +## Step 7. Build and Push your Acorn image + +Ready to release your Acorn app into the wild? +Let's package it up in a single Acorn image and distribute it via an OCI registry. + +> **Note**: This example uses GitHub's container registry `ghcr.io`. +> You want to push to DockerHub instead? The prefix is `docker.io`. +> Just make sure that you actually have write access to the target repository. + +```bash +# Login into your OCI registry, if needed (interactive) +acorn login ghcr.io + +# Build the Acorn image and tag it to your liking +acorn build -t ghcr.io/acorn-io/getting-started:v0.0.1 . + +# Push the newly built Acorn image +acorn push ghcr.io/acorn-io/getting-started:v0.0.1 +``` + +Now, everyone else can run your Acorn image via + +```bash +acorn run --name awesome-acorn ghcr.io/acorn-io/getting-started:v0.0.1 +``` + +## Interacting with an Acorn app + +### Execute a command inside the running container + +You can get an interactive shell into any running app or container with: + +```bash +acorn exec awesome-acorn +``` + +If there is more than one container in an app, you will be prompted to pick one. You can also run a specific command instead of getting a shell: + +```bash +acorn exec awesome-acorn env +``` + +### Reveal the auto-generated database secret + +```bash +# List all Acorn Secrets +$ acorn secrets +ALIAS NAME TYPE KEYS CREATED +awesome-acorn.quickstart-pg-pass quickstart-pg-pass-sqlv9 token [token] 139m ago + +# Reveal the one for the current app +$ acorn secret reveal awesome-acorn.quickstart-pg-pass +NAME TYPE KEY VALUE +quickstart-pg-pass-sqlv9 token token mssl8692sk47tfklx9bqnqflw7pqrk2ldb6cd9tckjlttpk4vsvpvl +``` + +### Start and Stop your app + +That's easy! + +```shell +acorn stop awesome-acorn +``` + +and + +```bash +acorn start awesome-acorn +``` + +### Remove your app + +If you're done with the app, wipe it from the cluster via + +```bash +acorn rm awesome-acorn +``` + +> Dangerous Pro-Tip: to remove **all** Acorn apps at once: `acorn rm $(acorn apps -qa)` + +## What's next? + +- [Explore all the other awesome Acorn commands](reference/command-line/acorn) +- [Read through the Acornfile reference](https://docs.acorn.io/reference/acornfile) +- [Have a look what makes up Acorn](60-architecture/01-ten-thousand-foot-view.md) +- [Try our hands on guide for a more in depth overview](https://docs.acorn.io/hands-on-with-acorn) diff --git a/docs/versioned_docs/version-0.10/40-admin/02-volumeclasses.md b/docs/versioned_docs/version-0.10/40-admin/02-volumeclasses.md new file mode 100644 index 000000000..75caf1bb0 --- /dev/null +++ b/docs/versioned_docs/version-0.10/40-admin/02-volumeclasses.md @@ -0,0 +1,39 @@ +--- +title: Volume Classes +--- +Volume classes allow you to define where and how volumes are created. They are an abstraction on top of [storage classes](https://kubernetes.io/docs/concepts/storage/storage-classes/). + +By default, Acorn will create volume classes with no restrictions for each storage class in your cluster. These volume classes will be available to every user of your cluster. You can add restrictions to these volume classes as described here. + +If you would like to manually control the volume classes, the installation flag [`--manage-volume-classes`](30-installation/02-options.md#manually-managing-volume-classes). Note that using this flag will remove the Acorn generated volume classes. + +## Project Volume Classes +A Project Volume Class is associated to a single project. Any apps in that project will have access to the volume class and its underlying storage class. Project Volume Classes in different projects won't interfere with each other, so you can have a Project Volume Class in different projects with the same name and different parameters. + +Here is an example of a Project Volume Class with all its configurable fields. +```yaml +kind: ProjectVolumeClass +apiVersion: admin.acorn.io/v1 +default: true # If no class is given for a volume, the default is chosen. Only one default per project. +description: A short description of the volume class +metadata: + name: volume-class-name + namespace: project-namespace +size: + min: 1G + max: 10G + default: 2G +storageClassName: local-path +allowedAccessModes: + # List of access modes allowed by this volume class, like: + - readWriteOnce + - readWriteMany +inactive: false # An inactive volume class can continue to be used by existing apps, but not by new apps. +``` + +If `min`, `max`, or `allowedAccessModes` are not given, then there are no restrictions for volumes using the class. If a Project Volume Class does not have a `default` size and a volume does not specify a size, then `10G` is used. + +## Cluster Volume Classes +Cluster Volume Classes are exactly the same as Project Volume Classes except that they are not namespaced. This means that Cluster Volume Classes are available to every app running in your cluster. + +Similar to Project Volume Classes, there can be only one default for the entire cluster. However, there can be a default Cluster Volume Class and a default Project Volume Class for any project; the Project Volume Class default will take precedence in this situation. Similarly, if a Cluster Volume Class and a Project Volume Class exist with the same name, then the Project Volume Class will take precedence. These rules are applied when deploying apps and also when using the [`acorn offerings volumeclasses`](100-reference/01-command-line/acorn_offerings_volumeclasses.md) command. \ No newline at end of file diff --git a/docs/versioned_docs/version-0.10/40-admin/03-computeclasses.md b/docs/versioned_docs/version-0.10/40-admin/03-computeclasses.md new file mode 100644 index 000000000..1c732c41a --- /dev/null +++ b/docs/versioned_docs/version-0.10/40-admin/03-computeclasses.md @@ -0,0 +1,78 @@ +--- +title: Compute Classes +--- +Compute classes are a way of defining scheduling for the applications running on Acorn. They allow you to define Affinities, Tolerations, and Resource Requirements for the Pods that applications will run on. + +## Project Compute Classes + +A Project Compute Class is associated to a single project. Any apps in that project will have access to the compute class and its configurations. Project Compute Classes in different projects won't interfere with each other, so you can have a Project Compute Class in different projects with the same name and different parameters. + +Here is an example of a Project Compute Class with all its configurable fields. + +```yaml +kind: ProjectComputeClass +apiVersion: admin.acorn.io/v1 +default: true # If no class is given for a workload, the default is chosen. Only one default per project. +description: A short description of the compute class +metadata: + name: workload-class-name + namespace: project-namespace +memory: + min: 1Gi + max: 2Gi + default: 1Gi # This default overrides the install-wide memory default + requestScaler: .5 # Scales the requested memory by this amount to allow over provisioning of memory. Containers will not be able to use more memory then the user requested amount. + values: # Specific values that are only allowed to be used. Default must be included in these values and max/min cannot be set. + - 1.5Gi +cpuScaler: 1 # This is used as a ratio of how many VCPUs to schedule per Gibibyte of memory. In this case it is 1 to 1. +resources: # memory and CPU can not be specified in the resources field. + limits: + gpu-vendor.example/example-limit: 1 + requests: + gpu-vendor.example/example-request: 1 +priorityClassName: foo # The priority class to use for Pods +runtimeClassName: bar # The runtime class name to use for Pods +tolerations: # The same toleration fields for Pods + - key: "foo" + operator: "Equal" + value: "bar" + effect: "NoSchedule" +affinity: # The same affinity fields for Pods + nodeAffinity: + requiredDuringSchedulingIgnoredDuringExecution: + nodeSelectorTerms: + - matchExpressions: + - key: foo + operator: In + values: + - bar +supportedRegions: ["local"] # should always be set to ["local"] +``` + +If `memory.min`, `memory.max`, `memory.values`, `resources`, `affinity`, and `tolerations` are not given, then there are no scheduling rules for workloads using the compute class. + +## Cluster Compute Classes + +Cluster Compute Classes are exactly the same as Project Compute Classes except that they are not namespaced. This means that Cluster Workload Classes are available to every app running in your cluster. + +Similar to Project Compute Classes, there can be only one default for the entire cluster. However, there can be a default Cluster Compute Class and a default Project Compute Class for any project; the Project Compute Class default will take precedence in this situation. Similarly, if a Cluster Compute Class and a Project Compute Class exist with the same name, then the Project Compute Class will take precedence. These rules are applied when deploying apps and also when using the [`acorn offerings volumeclasses`](100-reference/01-command-line/acorn_offerings_computeclasses.md) command. + +## Resource provisioning + +Compute classes are the primary way to carve up resources in the cluster. When configuring the computeClasses, you should look at the ammount of RAM you have on a host and determine the ratio of CPU to RAM you want to use. + +### Example no over provisioning + +If you have a 4vCPU machine with 16GiB of RAM you have a 4:16 ratio of CPU to RAM. + +If you want to use 1GiB of RAM per vCPU you would set the CPU scalar to .25. + +4 vCPU / 16GiB RAM = .25 vCPU per GiB of RAM + +### Example over provisioning + +Say you want to over provision the resources by 50% to allow higher utilization of the cluster. If you have the same 4vCPU machine with 16GiB of RAM you have a 4:16 ratio of CPU to RAM. You would still set the CPU scalar to .25. + +In that configuration you'll be able to run ~16 workloads. Some resources will be unavailable for workloads for system level processes needed to orchestrate the system. + +If you would like to be able to run ~32 workloads you would set the resourceScalar field to .5. This value will be used to scale the requested resources by the user. So if a user requests 1GiB of RAM, the scheduler will only request 512MiB for the workload. The user will only be able to use up to the 1GiB they requested. diff --git a/docs/versioned_docs/version-0.10/40-admin/80-alpha-image-allow-rules.md b/docs/versioned_docs/version-0.10/40-admin/80-alpha-image-allow-rules.md new file mode 100644 index 000000000..9c0a04f0d --- /dev/null +++ b/docs/versioned_docs/version-0.10/40-admin/80-alpha-image-allow-rules.md @@ -0,0 +1,165 @@ +--- +title: ImageAllowRules [Alpha] +--- + +ImageAllowRules (IARs) are an alpha-feature of Acorn, currently hidden behind a feature flag. +To enable them in your Acorn installation, use `acorn install --features image-allow-rules=true`. + +:::caution +Please read this page to completion before enabling IARs, as they can be quite disruptive. +::: + + +## How ImageAllowRules work + +The principle behind IARs is to make your cluster more secure. +If you enable this feature, you won't be able to deploy any Acorn image anymore without allowing it. +To do that, you have to create an `ImageAllowRule` resource. +If the app image is allowed by a single IAR in your project, it's good to run. + +:::note +Removing an IAR won't stop your running app, but will update the `image-allowed` status condition on the app. +::: + +## What makes up an ImageAllowRule + +Currently, IARs have two parts: + +1. The `images` scope (required) denotes which images the rule applies to. It uses the same syntax as the auto-upgrade pattern. Examples below. +2. The `signatures` rules (optional) define a set of image signatures and annotations on those signatures to make sure that an image was actually approved by someone or something, e.g. by your QA team. We're using [sigstore/cosign](https://docs.sigstore.dev/cosign/installation/) for everything related to signatures. + +## Example + +```yaml +apiVersion: api.acorn.io/v1 +kind: ImageAllowRule +metadata: + name: example-iar + namespace: acorn # your project name +images: + - ghcr.io/** # ** matches everything, * matches a single path item, # matches a number +signatures: + rules: + - signedBy: + anyOf: # one match is good enough + - | + -----BEGIN PUBLIC KEY----- + MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEo9QMl0ilxrBNFqOpifkhmKVZ14D8 + cUSzwOtALU9owM2ZRzE55OP4je2y9sTVvlNr59eZQ/Q4gsxHfo4EETEuog== + -----END PUBLIC KEY----- + allOf: [] # all signatures required + annotations: # those annotations have to be present on all signatures + match: # simple key-value pairs + qa: approved + expressions: # just like Kubernetes label selectors + - key: tests + operator: In # In, NotIn, Exists, DoesNotExist + values: + - passed + - ok +``` + +## About Signatures + +To sign an image, you can use [sigstore/cosign](https://docs.sigstore.dev/cosign/installation/) via the CLI. +You can download or build an Acorn image, sign it with cosign, annotate the signature (optional), then upload it to an OCI registry. +Afterwards, when you try to run that image in a protected cluster where the image is in scope of an IAR, Acorn will first ensure that: +- it matches the provided public keys +- matching signatures also have the required annotations + +If one or both of these conditions aren't met, Acorn will refuse to run the image. + +### Walkthrough + +Here's a full walkthrough to use Acorn with the ImageAllowRules feature in a fresh installation and with cosign signatures. +Please note that the exact output may be different for you, especially depending on the version of cosign you use. + +```bash +# 1. Create a fresh cluster and install Acorn - doesn't have to be k3d, you may also update your existing installation +$ k3d cluster create acorn +... + +$ acorn install --features image-allow-rules=true +... + +# 2. Pull some Acorn image and push it to another registry that you have push access to (Alternatively, build it from an Acornfile) +$ acorn pull ghcr.io/acorn-io/hello-world:latest +$ acorn tag ghcr.io/acorn-io/hello-world:latest my.registry.local/acorn/hello-world:latest +$ acorn push my.registry.local/acorn/hello-world:latest + +# 2.1 Faster using crane: +$ crane copy ghcr.io/acorn-io/hello-world:latest my.registry.local/acorn/hello-world:latest +... + +# 3. Get the digest +$ crane digest my.registry.local/acorn/hello-world:latest +sha256:1a6c64d2ccd0bb035f9c8196d3bfe72a7fdbddc4530dfcb3ab2a0ab8afb57eeb + +# 4. Generate a keypair if you don't have one already +$ cosign generate-key-pair +Enter password for private key: +Enter password for private key again: +WARNING: File cosign.key already exists. Overwrite? +Are you sure you would like to continue? [y/N] y +Private key written to cosign.key +Public key written to cosign.pub + +# 5. Sign the image with the newly generated key and an annotation that says `tag=notok` +$ cosign sign --key cosign.key -a tag=notok my.registry.local/acorn/hello-world@sha256:1a6c64d2ccd0bb035f9c8196d3bfe72a7fdbddc4530dfcb3ab2a0ab8afb57eeb +Enter password for private key: + + Note that there may be personally identifiable information associated with this signed artifact. + This may include the email address associated with the account with which you authenticate. + This information will be used for signing this artifact and will be stored in public transparency logs and cannot be removed later. + +By typing 'y', you attest that you grant (or have permission to grant) and agree to have this information stored permanently in transparency logs. +Are you sure you would like to continue? [y/N] y +tlog entry created with index: 15549911 +Pushing signature to: my.registry.local/acorn/hello-world + +# 6. Deploy a cluster-level image allow rule that will deny this image +$ cat << EOF | kubectl apply -f - +pipe heredoc> apiVersion: api.acorn.io/v1 +kind: ImageAllowRule +metadata: + name: testrule + namespace: acorn +images: + - my.registry.local/** +signatures: + rules: + - signedBy: + anyOf: + - | + -----BEGIN PUBLIC KEY----- + !!! Put your Public Key here !!! + -----END PUBLIC KEY----- + annotations: + match: + tag: ok +EOF +imageallowrule.api.acorn.io/testrule configured + +# 7. Try to run the image -> it should fail (because the annotation is wrong) + +$ acorn run my.registry.local/acorn/hello-world:latest + • WARNING: This application would like to use the image 'my.registry.local/acorn/hello-world:latest'. + This image is not trusted by any image allow rules in this project. + This could be VERY DANGEROUS to the cluster if you do not trust this + application. If you are unsure say no. + +? Do you want to allow this app to use this (POTENTIALLY DANGEROUS) image? [Use arrows to move, type to filter] +> NO + yes (this tag only) + repository (all images in this repository) + registry (all images in this registry) + all (all images out there) + +# Here, as an admin, you get to choose to have Acorn automatically generate an IAR for you to allow this image (without signatures) +# Repeating Step 5 with `-a tag=notok` and then continuing with steps 6 and 7, should make it work +... +``` + +## No need for YAML + +As you have seen in the last section, Acorn also prompts admins to allow an image that is not yet allowed to run. That's quite basic and will create an ImageAllowRule with only the `images` scope populated, no signatures required. diff --git a/docs/versioned_docs/version-0.10/60-architecture/01-ten-thousand-foot-view.md b/docs/versioned_docs/version-0.10/60-architecture/01-ten-thousand-foot-view.md new file mode 100644 index 000000000..20727382d --- /dev/null +++ b/docs/versioned_docs/version-0.10/60-architecture/01-ten-thousand-foot-view.md @@ -0,0 +1,33 @@ +--- +title: Ten-Thousand Foot View +--- + +The following is a high-level diagram of Acorn's architecture. + +![Architecture](/diagrams/architecture.drawio.svg) + +These components are described in more detail below. + +### CLI + +The Acorn CLI resides on the end user's machine and executes commands against an instance of Acorn running inside a Kubernetes cluster. + +### API Server + +The Acorn API server is a Kubernetes-style API that is made accessible through the Kubernetes [API aggregation layer](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/apiserver-aggregation/). + +By design, the Acorn CLI only interacts with the `api.acorn.io` API group in Kubernetes. This means that an Acorn user only needs RBAC permissions to the API group. The diagram shows the CLI talking to the Kubernetes API server because it is the entrypoint. It handles authentication and routing, but otherwise proxies the request to the Acorn API server. + +Upon receiving requests from the CLI, the Acorn API server will take various actions. Here are a few examples of such actions: + +- To launch an Acorn app, the Acorn API server will create an instance of the `AppInstance.internal.acorn.io` CRD. +- To build an Acorn image, where the CLI is expecting to have a long-lived interactive connection to the image building service (which is Buildkit), the Acorn API server just acts as a proxy. +- To display details about Acorn images, it will make requests to internal and external registries. + +### Controller + +The Acorn Controller is responsible for translating Acorn apps into actual Kubernetes resources such as Deployments, Services, and PersistentVolumes. It handles the entire lifecycle of such applications and ensures that the Kubernetes resources remain in sync with the Acorn app definition. + +### Buildkit and Internal Registry + +The image building service, Buildkit, and an internal image registry are deployed as sibling containers in a single pod. This simplifies the communication between the two components when Buildkit is building new Acorn images. diff --git a/docs/versioned_docs/version-0.10/60-architecture/02-security-considerations.md b/docs/versioned_docs/version-0.10/60-architecture/02-security-considerations.md new file mode 100644 index 000000000..aa036c7da --- /dev/null +++ b/docs/versioned_docs/version-0.10/60-architecture/02-security-considerations.md @@ -0,0 +1,228 @@ +--- +title: Security Considerations +--- + +## Report a Vulnerability + +Please email security@acorn.io to report a security vulnerability. + +You may optionally use GPG key `ed25519/2B480FBF4589035A` to encrypt the message: +``` +-----BEGIN PGP PUBLIC KEY BLOCK----- + +mDMEYumxgxYJKwYBBAHaRw8BAQdAOKLnuP8xUhoLv3W9Pt1dm9vHugQp6wfvAOXp +fdsec6y0IkFjb3JuIFNlY3VyaXR5IDxzZWN1cml0eUBhY29ybi5pbz6IkwQTFgoA +OxYhBA6PZhQ3ctoS4HilaitID79FiQNaBQJi6bGDAhsDBQsJCAcCAiICBhUKCQgL +AgQWAgMBAh4HAheAAAoJECtID79FiQNasGcA/0iK+CvUt4WR4EJQCat+59kDga4W +q93NusAccHpVmS2BAP91JcJ8OwZyV8IcW/dwcDFvBvH3A5R0BMejEYLeP+goBbg4 +BGLpsYMSCisGAQQBl1UBBQEBB0D+8r9ML4HBgrobV+rysJQ205UKIFmbgVTY5bmD +ywWsRAMBCAeIeAQYFgoAIBYhBA6PZhQ3ctoS4HilaitID79FiQNaBQJi6bGDAhsM +AAoJECtID79FiQNagEEA/2XN7UI70hZNVcm+kGTW04MQ1s57YVzwibGcB79AvIX+ +AP9aDhMMlbAOJTVFlBmkzQ6ERpCfakLvw+BM2hEv10uiAg== +=B32Z +-----END PGP PUBLIC KEY BLOCK----- +``` + +## Acorn System Access + +Acorn system components run with cluster admin privileges because it needs the ability to create namespaces and other objects on the user's behalf. End users have little required permissions. + +## User Tenancy + +Acorn allows multiple teams to deploy and manage Acorn apps on a cluster without interfering with each other. + +### Scope + +The unit of tenancy is the Acorn namespace, the default one is `acorn`. A user with access to that namespace will be able to see all Acorn apps running in that environment. They will be able to access the logs, containers, and endpoints. + +All Acorn CLI commands and the UI are scoped to the user's Acorn namespace. + +### RBAC + +Users will require CRUD access to all types from the `api.acorn.io` API group within their Acorn namespace. + +```shell +"apps" +"apps/log" +"builders" +"builders/port" +"builders/registryport" +"images" +"images/tag" +"images/push" +"images/pull" +"images/details" +"volumes" +"containerreplicas" +"containerreplicas/exec" +"credentials" +"secrets" +"secrets/reveal" +"infos" +``` + +Optionally, they might need access to create secrets and possibly CertManager objects for TLS certs in the users Acorn namespace. This is if the app team running the Acorn app will be creating secrets to pass in data. + +Users can be given access to multiple Acorn namespaces and will then be able to switch between them from the CLI. + +For convenience, the following roles are created by the Acorn installation, and can be used to give users access to the resources necessary to perform the corresponding tasks: +```shell +acorn:cluster:edit +acorn:cluster:view +acorn:project:admin +acorn:project:build +acorn:project:edit +acorn:project:view +acorn:project:view-logs +``` + +### Shared Image Registry + +Default installations of Acorn Runtime will deploy an OCI registry into Kubernetes, which will be the default image storage for all projects. +This registry is not secured with credentials. +Acorn's API server performs basic checks to try to prevent users from trivially accessing images that belong to other projects, but this is not guaranteed. + +You can configure Acorn to use an external OCI registry, but the credentials are shared between all projects, so the security implications around image access are the same. Future releases will improve upon this by providing a framework for isolating registries. + +## Credentials + +Credentials refer to credentials used to pull from and/or push to OCI registries. +In the future credentials in Acorn may be used for different types of services, but at the moment they are only used for OCI registries where Acorn images are stored. + +### Storage + +Credentials are stored within the cluster in a namespaced secret. +The Acorn API does not give access to the secret values of the credential, namely the password or token. +If a user has access to use the credential that does not mean they can see the credential value. +This makes it safe to share credentials in a team setting. + +### Scope/Access + +Credentials are valid for all Acorn apps and Acorn images in a namespace. +Any user that has privileges to push or pull and Acorn image will implicitly be using the credentials stored in that namespace. +Similarly any Acorn app that is deployed will use the credentials available in the namespace to pull the Acorn image and referenced Docker images. + +### CLI + +Credentials are managed with the [`acorn credential`](100-reference/01-command-line/acorn_credential.md) command. + +## Networking + +### Acorn app Network scopes + +Acorn can be used to package applications that can be used standalone, with other Acorns, and made available to non Acorn based workloads. +Modern day applications are loosely coupled over networking paths. + +Terminology: + +- Acorn image - An application with all its resources, dependencies and configuration, defined by a single Acornfile and packaged as an OCI image +- Acorn app - An instantiation of an Acorn image + +### Internal Acorn communication + +When composing an Acorn app that will only need to communicate with itself, you can define the `ports` section on the containers in the app. + +```acorn +containers: { + "my-app": { + build: { + context: "." + } + ports: [ + "4444:4444", // My internal endpoint + ] + } +} +``` + +In the example above other containers within the Acorn app would be able to communicate with `my-app` over port `4444`. + +### External Acorn app communications + +For services running outside of the Acorn app to communicate with your services, you need to expose the ports. Building on the above example. + +```acorn +containers: { + "my-app": { + build: { + context: "." + } + ports: { + internal: "4444:4444", // My internal endpoint + expose: "80:80", // My site + } + } +} +``` + +This will make it so workloads on the same cluster can communicate with your Acorn app on port 80. + +### Publishing + +If you need to expose your Acorn app to users and workloads outside of your cluster, you will need to publish your services. + +By default, all HTTP services are automatically published via the underlying Ingress controller. To publish no ports you can use `-p none`. + +:::caution + +Note this is going to go through a major refactor and likely to change, but the concept holds. +::: + +Publishing services is a runtime level decision for the user to make. If a user wants to publish all exposed ports when launching the Acorn app the `-P` flag is used. + +```shell +acorn run -P [APP-IMAGE] +``` + +In our example this would expose port 80 through the Ingress controller of the underlying Kubernetes cluster. + +If the user wants to expose under an explicit name, the user can do the following: + +```shell +acorn run -p my-app.example.com:my-app [APP-IMAGE] +``` + +That will expose the application under the hostname `my-app.example.com`. There is no need to pass a publish flag. + +To see which services in your Acorn app can be published run `acorn run [APP-IMAGE] --help` + +```shell +> acorn run [APP-IMAGE] --help +Volumes: mysql-data-0, mysql-backup-vol +Secrets: backup-user-credentials, create-backup-user, user-provided-data, mariadb-0-client-config, mariadb-0-mysqld-config, mariadb-0-galera-config, root-credentials, db-user-credentials +Container: mariadb-0 +Ports: mariadb-0:3306/tcp + + --backup-schedule string Backup Schedule + --boot-strap-index int Set server to boot strap a new cluster. Default (0) + --cluster-name string Galera: cluster name + --custom-mariadb-config string User provided MariaDB config + --db-name string Specify the name of the database to create. Default(acorn) + --db-user-name string Specify the username of db user + --force-recover When recovering the cluster this will force safe_to_bootstrap in grastate.dat for the bootStrapIndex node. + --recovery Run cluster into recovery mode. + --replicas int Number of nodes to run in the galera cluster. Default (1) + --restore-from-backup string Restore from Backup. Takes a backup file name +``` + +Ports that can be exposed are listed under the `Ports` setting. + +If you have an app that exposes a TCP endpoint instead of HTTP like: + +```acorn +containers: { + // ... + mysql: { + image: mysql + ports: expose: "3306:3306" + // ... + } + // ... +} +``` + +You can expose these outside the cluster through a loadbalancer endpoint in the following way. + +```shell +> acorn run -p 3306:3306 [MY-APP-IMAGE] +``` diff --git a/docs/versioned_docs/version-0.10/60-architecture/_category_.yaml b/docs/versioned_docs/version-0.10/60-architecture/_category_.yaml new file mode 100644 index 000000000..3fad4ef92 --- /dev/null +++ b/docs/versioned_docs/version-0.10/60-architecture/_category_.yaml @@ -0,0 +1 @@ +label: Architecture diff --git a/docs/versioned_sidebars/version-0.10-sidebars.json b/docs/versioned_sidebars/version-0.10-sidebars.json new file mode 100644 index 000000000..cf2178452 --- /dev/null +++ b/docs/versioned_sidebars/version-0.10-sidebars.json @@ -0,0 +1,107 @@ +{ + "sidebar": [ + "home", + { + "type": "category", + "label": "Installation", + "items": [ + "installation/installing", + "installation/options", + "installation/upgrading", + "installation/uninstalling" + ], + "collapsed": true + }, + "getting-started", + { + "type": "category", + "label": "Administration", + "items": [ + "admin/volumeclasses", + "admin/computeclasses", + "admin/alpha-image-allow-rules" + ] + }, + { + "type": "category", + "label": "Architecture", + "items": [ + "architecture/ten-thousand-foot-view", + "architecture/security-considerations" + ], + "collapsed": true + }, + { + "type": "category", + "label": "Reference", + "items": [ + { + "type": "category", + "label": "Command Line", + "items": [ + "reference/command-line/acorn", + "reference/command-line/acorn_all", + "reference/command-line/acorn_build", + "reference/command-line/acorn_check", + "reference/command-line/acorn_container", + "reference/command-line/acorn_container_kill", + "reference/command-line/acorn_copy", + "reference/command-line/acorn_credential", + "reference/command-line/acorn_credential_login", + "reference/command-line/acorn_credential_logout", + "reference/command-line/acorn_dashboard", + "reference/command-line/acorn_dev", + "reference/command-line/acorn_edit", + "reference/command-line/acorn_events", + "reference/command-line/acorn_exec", + "reference/command-line/acorn_image", + "reference/command-line/acorn_image_copy", + "reference/command-line/acorn_image_details", + "reference/command-line/acorn_image_rm", + "reference/command-line/acorn_info", + "reference/command-line/acorn_install", + "reference/command-line/acorn_job", + "reference/command-line/acorn_job_restart", + "reference/command-line/acorn_login", + "reference/command-line/acorn_logout", + "reference/command-line/acorn_logs", + "reference/command-line/acorn_project", + "reference/command-line/acorn_project_create", + "reference/command-line/acorn_project_rm", + "reference/command-line/acorn_project_update", + "reference/command-line/acorn_project_use", + "reference/command-line/acorn_ps", + "reference/command-line/acorn_pull", + "reference/command-line/acorn_push", + "reference/command-line/acorn_offerings", + "reference/command-line/acorn_offerings_computeclasses", + "reference/command-line/acorn_offerings_regions", + "reference/command-line/acorn_offerings_volumeclasses", + "reference/command-line/acorn_port-forward", + "reference/command-line/acorn_render", + "reference/command-line/acorn_rm", + "reference/command-line/acorn_run", + "reference/command-line/acorn_secret", + "reference/command-line/acorn_secret_create", + "reference/command-line/acorn_secret_edit", + "reference/command-line/acorn_secret_update", + "reference/command-line/acorn_secret_encrypt", + "reference/command-line/acorn_secret_reveal", + "reference/command-line/acorn_secret_rm", + "reference/command-line/acorn_start", + "reference/command-line/acorn_stop", + "reference/command-line/acorn_tag", + "reference/command-line/acorn_uninstall", + "reference/command-line/acorn_update", + "reference/command-line/acorn_version", + "reference/command-line/acorn_volume", + "reference/command-line/acorn_volume_rm", + "reference/command-line/acorn_wait" + ] + } + ], + "collapsed": true + }, + "faq" + ] +} diff --git a/docs/versions.json b/docs/versions.json index 053ac41d9..da393ea61 100644 --- a/docs/versions.json +++ b/docs/versions.json @@ -1,4 +1,5 @@ [ + "0.10", "0.9", "0.8", "0.7",