From 0c95d601fcf226a0dcd9e32c50d4e92f14d43f33 Mon Sep 17 00:00:00 2001 From: Jack Decker <24392469+jackowfish@users.noreply.github.com> Date: Fri, 23 Jan 2026 16:03:26 -0500 Subject: [PATCH 1/2] docs: add porter apply CLI command reference Add documentation for the new porter apply command which allows users to apply porter.yaml configurations from the CLI. --- mint.json | 26 +- .../cli/command-reference/porter-apply.mdx | 245 ++++++++++++++++++ 2 files changed, 247 insertions(+), 24 deletions(-) create mode 100644 standard/cli/command-reference/porter-apply.mdx diff --git a/mint.json b/mint.json index 17d43cb..b8b3943 100644 --- a/mint.json +++ b/mint.json @@ -132,10 +132,10 @@ "pages": [ "cli/installation", "cli/basic-usage", - "cli/v1-and-v2", { - "group": "v2 Command Reference", + "group": "Command Reference", "pages": [ + "standard/cli/command-reference/porter-apply", "standard/cli/command-reference/porter-auth", "standard/cli/command-reference/porter-cluster", "standard/cli/command-reference/porter-config", @@ -146,28 +146,6 @@ "standard/cli/command-reference/porter-target", "standard/cli/command-reference/porter-job" ] - }, - { - "group": "v1 Command Reference", - "pages": [ - "enterprise/cli/command-reference/porter-auth", - "enterprise/cli/command-reference/porter-cluster", - "enterprise/cli/command-reference/porter-config", - "enterprise/cli/command-reference/porter-connect", - "enterprise/cli/command-reference/porter-create", - "enterprise/cli/command-reference/porter-delete", - "enterprise/cli/command-reference/porter-get", - "enterprise/cli/command-reference/porter-helm", - "enterprise/cli/command-reference/porter-job", - "enterprise/cli/command-reference/porter-kubectl", - "enterprise/cli/command-reference/porter-list", - "enterprise/cli/command-reference/porter-logs", - "enterprise/cli/command-reference/porter-project", - "enterprise/cli/command-reference/porter-registry", - "enterprise/cli/command-reference/porter-run", - "enterprise/cli/command-reference/porter-stack", - "enterprise/cli/command-reference/porter-update" - ] } ] }, diff --git a/standard/cli/command-reference/porter-apply.mdx b/standard/cli/command-reference/porter-apply.mdx new file mode 100644 index 0000000..95b9003 --- /dev/null +++ b/standard/cli/command-reference/porter-apply.mdx @@ -0,0 +1,245 @@ +--- +title: 'porter apply' +sidebarTitle: 'porter apply' +--- + +`porter apply` is the primary command for deploying applications using configuration-as-code. It reads a `porter.yaml` file, **builds a new container image**, and **deploys your application** to the cluster. + +By default, `porter apply` performs a full build and deploy cycle. Use `--no-build` to skip building and deploy with an existing image. + +You can also pass environment variables and secrets directly via command-line flags (`--variables`, `--secrets`) without modifying your `porter.yaml`. + + +This command is the recommended way to deploy applications in CI/CD pipelines and for version-controlled infrastructure. + + +## Usage + +```bash +porter apply -f porter.yaml [flags] +``` + +## Prerequisites + +- You've logged in to the Porter CLI after running [porter auth login](/standard/cli/command-reference/porter-auth) +- You're connected to the correct project by running [porter config set-project](/standard/cli/command-reference/porter-config) +- You're connected to the correct cluster by running [porter config set-cluster](/standard/cli/command-reference/porter-config) + +## Options + +### Required Flags + +| Flag | Short | Description | +|------|-------|-------------| +| `--file` | `-f` | Path to the `porter.yaml` configuration file | + +### Deployment Options + +| Flag | Short | Description | +|------|-------|-------------| +| `--app` | | Override the app name specified in `porter.yaml` | +| `--target` | `-x` | Specify a deployment target (name or ID) | +| `--wait` | `-w` | Wait for the deployment to complete before exiting | +| `--preview` | `-p` | Deploy to a preview environment based on current git branch | + +### Build Options + +| Flag | Description | +|------|-------------| +| `--no-build` | Skip building a new image and deploy with an existing image | +| `--no-pull` | Don't pull the previous image before building | +| `--tag` | Specify a custom image tag (overrides value in porter.yaml) | +| `--image-repository` | Set the image repository to use | +| `--build-context` | Override the build context directory | +| `--build-method` | Set build method: `docker` or `pack` | +| `--dockerfile` | Override the Dockerfile path (for docker builds) | +| `--builder` | Set the builder to use (for pack builds) | +| `--attach-buildpacks` | Attach buildpacks to use (for pack builds) | +| `--remote` | Build remotely using kpack in the cluster instead of locally (experimental) | +| `--verbose` | Show verbose output during build | + +### Environment Options + +| Flag | Description | +|------|-------------| +| `--variables` | Set environment variables as key=value pairs (overrides porter.yaml) | +| `--secrets` | Set secrets as key=value pairs (overrides porter.yaml) | + +### Validation Options + +| Flag | Description | +|------|-------------| +| `--validate` | Validate the `porter.yaml` file without deploying | +| `--dry-run` | Perform server-side validation without applying changes | +| `--exact` | Disable config merging with existing app configuration | + +### Advanced Options + +| Flag | Short | Description | +|------|-------|-------------| +| `--predeploy` | | Run the predeploy job before deploying services | +| `--helm-overrides-file` | `-v` | Path to a file containing Helm value overrides | +| `--attach-env-groups` | | Comma-separated list of environment groups to attach | + +## Environment Variables + +You can also configure `porter apply` using environment variables: + +| Variable | Description | +|----------|-------------| +| `PORTER_APP_NAME` | Override the app name (alternative to `--app`) | +| `PORTER_PROJECT` | Target project ID | +| `PORTER_CLUSTER` | Target cluster ID | +| `PORTER_TOKEN` | Authentication token | + +## Examples + + +```bash Basic Deployment +# Deploy using porter.yaml in the current directory +porter apply -f porter.yaml +``` + +```bash Wait for Completion +# Deploy and wait for the deployment to complete +porter apply -f porter.yaml +``` + +```bash Custom App Name +# Deploy with a different app name +porter apply -f porter.yaml --app my-staging-app +``` + +```bash Preview Environment +# Deploy to a preview environment +porter apply -f porter.yaml --preview +``` + +```bash Validation Only +# Validate the configuration without deploying +porter apply -f porter.yaml --validate +``` + +```bash CI/CD Pipeline +# Deploy in a CI/CD pipeline with explicit configuration +PORTER_TOKEN=$PORTER_DEPLOY_TOKEN \ +PORTER_PROJECT=$PROJECT_ID \ +PORTER_CLUSTER=$CLUSTER_ID \ +porter apply -f porter.yaml +``` + +```bash Skip Build +# Deploy using an existing image (skip build step) +porter apply -f porter.yaml --no-build --tag v1.2.3 +``` + +```bash With Predeploy +# Run predeploy job before deployment +porter apply -f porter.yaml --predeploy --wait +``` + +```bash With Environment Variables +# Deploy with runtime environment variables and secrets +porter apply -f porter.yaml --variables LOG_LEVEL=debug,NODE_ENV=production --secrets API_KEY=secret123 +``` + + +## Workflow + +When you run `porter apply`, the following steps occur: + + + + Porter reads and validates your `porter.yaml` file + + + Porter builds and pushes a new container image (unless `--no-build` is specified) + + + If `--predeploy` is specified or `predeploy` is defined in porter.yaml, the predeploy job runs first + + + Porter deploys or updates all services defined in the configuration + + + If `--wait` is specified, Porter waits for all services to become healthy + + + +## Configuration File + +The `porter apply` command expects a `porter.yaml` file. For detailed documentation on all available configuration options, see the [porter.yaml Reference](/deploy/configuration-as-code/reference). + +### Minimal Example + +```yaml +version: v2 +name: my-app + +services: + - name: web + type: web + run: npm start + port: 3000 + cpuCores: 0.5 + ramMegabytes: 512 +``` + +## CI/CD Integration + + +For CI/CD pipelines, use environment variables for authentication and the `--wait` flag to ensure deployments complete before the pipeline continues. + + +### GitHub Actions Example + +```yaml +- name: Deploy to Porter + env: + PORTER_TOKEN: ${{ secrets.PORTER_TOKEN }} + PORTER_PROJECT: ${{ secrets.PORTER_PROJECT }} + PORTER_CLUSTER: ${{ secrets.PORTER_CLUSTER }} + run: porter apply -f porter.yaml +``` + +### GitLab CI Example + +```yaml +deploy: + script: + - porter apply -f porter.yaml + variables: + PORTER_TOKEN: $PORTER_TOKEN + PORTER_PROJECT: $PORTER_PROJECT + PORTER_CLUSTER: $PORTER_CLUSTER +``` + +## Troubleshooting + + +If your deployment fails, check the following common issues: +- Ensure your `porter.yaml` is valid by running `porter apply -f porter.yaml --validate` +- Verify you're authenticated with `porter auth login` +- Check that your project and cluster are correctly configured with `porter config` + + +### Validation Errors + +Run with `--validate` to check your configuration: + +```bash +porter apply -f porter.yaml --validate +``` + +### Dry Run + +Use `--dry-run` for server-side validation without making changes: + +```bash +porter apply -f porter.yaml --dry-run +``` + +## Related Commands + +- [porter app update](/standard/cli/command-reference/porter-app#porter-update) - Update an app without building +- [porter app yaml](/standard/cli/command-reference/porter-app#porter-yaml) - Export the current app configuration as YAML From f2624ea5ccf1863da4460dbc7fc25ac6af2f06a4 Mon Sep 17 00:00:00 2001 From: Jack Decker <24392469+jackowfish@users.noreply.github.com> Date: Fri, 23 Jan 2026 16:19:20 -0500 Subject: [PATCH 2/2] trigger CI