From bd426895b97c728d626e9a4329824884c6c7cedd Mon Sep 17 00:00:00 2001 From: Kim Christensen Date: Fri, 24 May 2024 22:02:42 +0200 Subject: [PATCH] Fix some more Signed-off-by: Kim Christensen --- docs/.htmltest.yml | 15 +- docs/content/docs/_index.md | 2 +- docs/content/docs/administration/_index.md | 8 +- .../administration/collect-diag-porter.md | 4 +- .../docs/administration/inspecting-bundles.md | 2 +- .../administration/move-bundles-airgapped.md | 2 +- docs/content/docs/best-practices/_index.md | 6 +- .../docs/best-practices/ci-pipeline.md | 4 +- docs/content/docs/bundle/manifest/_index.md | 2 +- .../bundle/manifest/file-format/_index.md | 4 +- .../docs/configuration/configuration.md | 2 +- docs/content/docs/contribute/work-with-us.md | 2 +- docs/content/docs/development/_index.md | 6 +- .../development/authoring-a-bundle/_index.md | 10 +- .../authoring-a-bundle/create-a-bundle.md | 14 +- .../authoring-a-bundle/distribute-bundles.md | 4 +- .../authoring-a-bundle/using-templates.md | 4 +- .../working-with-dependencies.md | 2 +- docs/content/docs/development/dist-a-mixin.md | 2 +- docs/content/docs/faq/_index.md | 4 +- docs/content/docs/how-to-guides/_index.md | 4 +- .../docs/how-to-guides/work-with-plugins.md | 2 +- docs/content/docs/integrations/_index.md | 8 +- docs/content/docs/integrations/gke.md | 2 +- docs/content/docs/integrations/kind.md | 2 +- docs/content/docs/introduction/_index.md | 4 +- .../concepts-and-components/_index.md | 18 +-- .../intro-configuration.md | 4 +- .../concepts-and-components/intro-mixins.md | 4 +- .../intro-parameters.md | 14 +- docs/content/docs/operations/_index.md | 12 +- .../docs/operations/create-porter-config.md | 16 +- .../docs/operations/examine-bundles.md | 2 +- .../docs/operations/manage-installations.md | 2 +- docs/content/docs/quickstart/_index.md | 6 +- docs/content/docs/quickstart/bundles.md | 6 +- docs/content/docs/quickstart/configuration.md | 4 +- docs/content/docs/quickstart/desired-state.md | 6 +- docs/content/docs/quickstart/parameters.md | 2 +- .../docs/references/docker-images/_index.md | 4 +- .../docs/references/docker-images/agent.md | 139 +++++++++++++++++- .../docs/references/examples/airgap.md | 2 +- .../docs/references/examples/docker.md | 62 +++++++- .../docs/references/file-formats/_index.md | 2 +- .../file-formats/credential-set/_index.md | 2 +- .../file-formats/installation/_index.md | 2 +- .../file-formats/parameter-set/_index.md | 2 +- .../references/file-formats/plugins/_index.md | 2 +- .../content/docs/references/library/_index.md | 81 +++++++++- docs/content/docs/references/linter.md | 2 +- docs/content/docs/troubleshooting/_index.md | 2 +- docs/content/mixin-dev-guide/commands.md | 11 +- docs/content/mixins/exec.md | 2 +- .../testdata/bundles/exec-outputs/README.md | 2 +- 54 files changed, 406 insertions(+), 128 deletions(-) diff --git a/docs/.htmltest.yml b/docs/.htmltest.yml index 270eccc6d..c28d54367 100644 --- a/docs/.htmltest.yml +++ b/docs/.htmltest.yml @@ -1,14 +1,25 @@ IgnoreURLs: - ^/forum$ - ^/zoom/dev/$ - - ^/dev-meeting$ + - ^/dev-meeting - ^/calendar/$ - - ^/find-issue/$ + - ^/find-issue - ^/board/ - ^/roadmap - ^/src - ^/examples - ^/forum + - ^/packages + - ^/schema/ - ^/docker-mixin/src + - ^/mailing-list/$ + - ^/videos/?$ + - ^/devstats/$ + - ^/twitter/$ + - ^/slack/?$ + - ^/v\d\. + - ^/latest/ + - ^/community/src/ + - http://localhost:1313/docs IgnoreAltMissing: true IgnoreInternalEmptyHash: true \ No newline at end of file diff --git a/docs/content/docs/_index.md b/docs/content/docs/_index.md index b461bade5..391c8a131 100644 --- a/docs/content/docs/_index.md +++ b/docs/content/docs/_index.md @@ -10,4 +10,4 @@ Porter is an open-source project that packages your application, client tools, c - [Porter Overview](/architecture/) - [Install Porter](/install/) - [Quick Start](/quickstart/) -- [Frequently Asked Questions](/faq) +- [Frequently Asked Questions](/faq/) diff --git a/docs/content/docs/administration/_index.md b/docs/content/docs/administration/_index.md index 413c4ad88..7f7692613 100644 --- a/docs/content/docs/administration/_index.md +++ b/docs/content/docs/administration/_index.md @@ -7,8 +7,8 @@ weight: 6 **Learn about managing Administration** {{< cards >}} -{{< card link="inspecting-bundles" title="Inspecting Bundles" >}} -{{< card link="copy-bundles" title="Copy Bundles" >}} -{{< card link="move-bundles-airgapped" title="Move Bundles Across Airgapped Environments" >}} -{{< card link="collect-diag-porter" title="Collect Diagnostics from Porter" >}} +{{< card link="inspecting-bundles/" title="Inspecting Bundles" >}} +{{< card link="copy-bundles/" title="Copy Bundles" >}} +{{< card link="move-bundles-airgapped/" title="Move Bundles Across Airgapped Environments" >}} +{{< card link="collect-diag-porter/" title="Collect Diagnostics from Porter" >}} {{< /cards >}} diff --git a/docs/content/docs/administration/collect-diag-porter.md b/docs/content/docs/administration/collect-diag-porter.md index bc4c01a11..ea301bf2c 100644 --- a/docs/content/docs/administration/collect-diag-porter.md +++ b/docs/content/docs/administration/collect-diag-porter.md @@ -41,7 +41,7 @@ See [Telemetry Settings][telemetry] for all the supported configuration settings [compat]: https://opentelemetry.io/vendors/ [OpenTelemetry environment variables]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.8.0/specification/protocol/exporter.md -[telemetry]: /configuration/#telemetry -[Log Settings]: /configuration/#logs +[telemetry]: /docs/configuration/configuration/#telemetry +[Log Settings]: /docs/configuration/configuration/#logs [OpenTelemetry]: https://opentelemetry.io [otel-jaeger bundle]: /examples/src/otel-jaeger diff --git a/docs/content/docs/administration/inspecting-bundles.md b/docs/content/docs/administration/inspecting-bundles.md index f3901bc9f..1debd1125 100644 --- a/docs/content/docs/administration/inspecting-bundles.md +++ b/docs/content/docs/administration/inspecting-bundles.md @@ -7,7 +7,7 @@ aliases: - /inspect-bundle/ --- -You've found a bundle that you'd like to use, but you'd like to what images will be used after you install the bundle. You can use the `porter inspect` command to see this information. If you'd like to see additional information, like parameters, credentials, and outputs, see the [explain](/operations/examine-bundles/) command. +You've found a bundle that you'd like to use, but you'd like to what images will be used after you install the bundle. You can use the `porter inspect` command to see this information. If you'd like to see additional information, like parameters, credentials, and outputs, see the [explain](/docs/operations/examine-bundles/) command. When a bundle is published, the images that it will use are copied into the location of the published bundle. This simplifies access control and management of artifacts in the repository. The `inspect` command will show the invocation images, as well as any referenced images, that will be used as a result of performing actions like install nad upgrade. For each image, you will see the image reference that will be used, along with the original image reference that the image was copied from. diff --git a/docs/content/docs/administration/move-bundles-airgapped.md b/docs/content/docs/administration/move-bundles-airgapped.md index 99254aaf0..2a23ea906 100644 --- a/docs/content/docs/administration/move-bundles-airgapped.md +++ b/docs/content/docs/administration/move-bundles-airgapped.md @@ -16,7 +16,7 @@ At a high level, this involves the following steps: 4. Install the bundle referencing the new location of the bundle inside the airgapped network.
- a drawing showing two networks side by side, separated by an airgap. Network A has a docker registry with a copy of a bundle that includes the bundle.json, installer and the whalesayd image. An arrow labeled porter archive leads to a box with all those components in a single box labeled whalegap.tgz. Then another arrow labeled with a disc goes across the airgap, copying the same whalegap.tgz box wit its components into Network B. Then a final arrow labeled porter publish puts a copy of the bundle and its contents in Registry B, inside Network B. + a drawing showing two networks side by side, separated by an airgap. Network A has a docker registry with a copy of a bundle that includes the bundle.json, installer and the whalesayd image. An arrow labeled porter archive leads to a box with all those components in a single box labeled whalegap.tgz. Then another arrow labeled with a disc goes across the airgap, copying the same whalegap.tgz box wit its components into Network B. Then a final arrow labeled porter publish puts a copy of the bundle and its contents in Registry B, inside Network B.
Moving the whalegap bundle across an airgap
diff --git a/docs/content/docs/best-practices/_index.md b/docs/content/docs/best-practices/_index.md index 68b9ac01f..1c11432ca 100644 --- a/docs/content/docs/best-practices/_index.md +++ b/docs/content/docs/best-practices/_index.md @@ -6,7 +6,7 @@ weight: 11 **Follow Best Practices** {{< cards >}} -{{< card link="credentials-or-parameters" title="When to use credentials vs parameters" >}} -{{< card link="exec-mixin" title="Best Practices for the mixin." >}} -{{< card link="ci-pipeline" title="Best practices for Porter in a CI pipeline" >}} +{{< card link="credentials-or-parameters/" title="When to use credentials vs parameters" >}} +{{< card link="exec-mixin/" title="Best Practices for the mixin." >}} +{{< card link="ci-pipeline/" title="Best practices for Porter in a CI pipeline" >}} {{< /cards >}} diff --git a/docs/content/docs/best-practices/ci-pipeline.md b/docs/content/docs/best-practices/ci-pipeline.md index b9c9888ce..57745cfc4 100644 --- a/docs/content/docs/best-practices/ci-pipeline.md +++ b/docs/content/docs/best-practices/ci-pipeline.md @@ -78,7 +78,7 @@ You can also specify the version of the mixin by adding the version flag. For ex run: porter mixins install az --version v0.4.2 ``` -Take a look at the [documentation](/mixins) to see all available mixins and how to know what command to run to install them. The documentation provides install commands for each mixin. The command `porter mixin search` lists all the mixins created by the community. Depending on if the URL is an atom feed or a github url you can install the mixin using +Take a look at the [documentation](/mixins/) to see all available mixins and how to know what command to run to install them. The documentation provides install commands for each mixin. The command `porter mixin search` lists all the mixins created by the community. Depending on if the URL is an atom feed or a github url you can install the mixin using ```yaml porter mixins install NAME --feed-url ATOM_URL @@ -111,7 +111,7 @@ If you are not the only one contributing to the repository and other contributor ### Use credential files -If you were using credentials in your bundle, you will need to set up a credential file in your repository to use with your workflow. For example, if you run `porter credentials create mybun.json`, a JSON file named mybun.json is created. The resulting [credential set template file](/reference/file-formats/#credential-set) (which does not contain any sensitive credentials) is located in the current directory. You can run `porter credentials apply mybun.json` to apply the changes. If the specified credential set already exists, the changes will override the existing credential set, otherwise the apply command will create a new credential set. Then, to install your bundle with the newly created credential set, you would run the following: +If you were using credentials in your bundle, you will need to set up a credential file in your repository to use with your workflow. For example, if you run `porter credentials create mybun.json`, a JSON file named mybun.json is created. The resulting [credential set template file](/docs/references/file-formats/credential-set/) (which does not contain any sensitive credentials) is located in the current directory. You can run `porter credentials apply mybun.json` to apply the changes. If the specified credential set already exists, the changes will override the existing credential set, otherwise the apply command will create a new credential set. Then, to install your bundle with the newly created credential set, you would run the following: ```yaml porter install -c diff --git a/docs/content/docs/bundle/manifest/_index.md b/docs/content/docs/bundle/manifest/_index.md index a234e74b9..d7702310d 100644 --- a/docs/content/docs/bundle/manifest/_index.md +++ b/docs/content/docs/bundle/manifest/_index.md @@ -619,7 +619,7 @@ be copied into the final bundle so that you can access them at runtime. The path ## See Also -* [Manifest File Format](/docs/reference/file-formats/#manifest) +* [Manifest File Format](/docs/bundle/manifest/file-format/) * [Using Mixins](/use-mixins/) * [Bundle Dependencies](/docs/development/authoring-a-bundle/working-with-dependencies/) * [Parameters, Credentials, Outputs, and Images in Porter](/wiring/) diff --git a/docs/content/docs/bundle/manifest/file-format/_index.md b/docs/content/docs/bundle/manifest/file-format/_index.md index 342fd62a6..8ae9cad8d 100644 --- a/docs/content/docs/bundle/manifest/file-format/_index.md +++ b/docs/content/docs/bundle/manifest/file-format/_index.md @@ -25,7 +25,7 @@ Below are schema versions for the Porter manifest, and the corresponding Porter Sometimes you may want to work with a different version of a resource than what is supported by Porter, especially when migrating from one version of Porter to another. The [schema-check] configuration setting allows you to change how Porter behaves when the schemaVersion of a resource doesn't match Porter's supported version. -[schema-check]: /configuration/#schema-check +[schema-check]: /docs/configuration/configuration/#schema-check ## Example @@ -233,7 +233,7 @@ status: ## Next Steps -* [Create a Bundle](/development/authoring-a-bundle/create-a-bundle/) +* [Create a Bundle](/docs/development/authoring-a-bundle/create-a-bundle/) [semver v2]: https://semver.org/spec/v2.0.0.html [manifest-schema]: https://raw.githubusercontent.com/getporter/porter/main/pkg/schema/manifest.schema.json diff --git a/docs/content/docs/configuration/configuration.md b/docs/content/docs/configuration/configuration.md index e2c295fe7..d6eb99c2b 100644 --- a/docs/content/docs/configuration/configuration.md +++ b/docs/content/docs/configuration/configuration.md @@ -227,7 +227,7 @@ Use the trace and logs configuration sections below to configure how logs and te #### Logs -Porter can be configured to [write a logfile for each command](/administration/collect-diag-porter/#logs). +Porter can be configured to [write a logfile for each command](/docs/administration/collect-diag-porter/#logs). The following log settings are available: diff --git a/docs/content/docs/contribute/work-with-us.md b/docs/content/docs/contribute/work-with-us.md index edb1c5554..20839fdff 100644 --- a/docs/content/docs/contribute/work-with-us.md +++ b/docs/content/docs/contribute/work-with-us.md @@ -105,4 +105,4 @@ maintainer to admin.

Sound like fun? 👍 Join us!

[contribution ladder]: /src/CONTRIBUTION_LADDER.md -[Slack]: /docs/community/#slack +[Slack]: /community/#slack diff --git a/docs/content/docs/development/_index.md b/docs/content/docs/development/_index.md index 23886bad4..6809cd2e6 100644 --- a/docs/content/docs/development/_index.md +++ b/docs/content/docs/development/_index.md @@ -7,7 +7,7 @@ weight: 7 **Learn about using Porter for Development** {{< cards >}} -{{< card link="authoring-a-bundle" title="Authoring a Bundle" >}} -{{< card link="dev-a-mixin" title="Developing a Mixin" >}} -{{< card link="dist-a-mixin" title="Distributing a Mixin" >}} +{{< card link="authoring-a-bundle/" title="Authoring a Bundle" >}} +{{< card link="dev-a-mixin/" title="Developing a Mixin" >}} +{{< card link="dist-a-mixin/" title="Distributing a Mixin" >}} {{< /cards >}} diff --git a/docs/content/docs/development/authoring-a-bundle/_index.md b/docs/content/docs/development/authoring-a-bundle/_index.md index f76ac1420..3d7b3143a 100644 --- a/docs/content/docs/development/authoring-a-bundle/_index.md +++ b/docs/content/docs/development/authoring-a-bundle/_index.md @@ -7,9 +7,9 @@ weight: 1 **Learn about Authoring a Bundle** {{< cards >}} -{{< card link="create-a-bundle" title="Create a Bundle" >}} -{{< card link="use-custom-dockerfile" title="Using a Custom Dockerfile" >}} -{{< card link="working-with-dependencies" title="Working with Dependencies" >}} -{{< card link="using-templates" title="Using Templates" >}} -{{< card link="distribute-bundles" title="Distributing a Bundle" >}} +{{< card link="create-a-bundle/" title="Create a Bundle" >}} +{{< card link="use-custom-dockerfile/" title="Using a Custom Dockerfile" >}} +{{< card link="working-with-dependencies/" title="Working with Dependencies" >}} +{{< card link="using-templates/" title="Using Templates" >}} +{{< card link="distribute-bundles/" title="Distributing a Bundle" >}} {{< /cards >}} diff --git a/docs/content/docs/development/authoring-a-bundle/create-a-bundle.md b/docs/content/docs/development/authoring-a-bundle/create-a-bundle.md index 64f521cd8..a2c577012 100644 --- a/docs/content/docs/development/authoring-a-bundle/create-a-bundle.md +++ b/docs/content/docs/development/authoring-a-bundle/create-a-bundle.md @@ -27,7 +27,7 @@ You must [install Porter], and optionally can use the [Porter Visual Studio Code ## Create a Bundle -Use the [porter create](/cli/porter_create) command to scaffold a new bundle in the current directory. +Use the [porter create](/cli/porter_create/) command to scaffold a new bundle in the current directory. The directory containing the files for the bundle is called the **bundle directory**. The generated bundle is very similar to the [hello example bundle] and prints out "Hello World" when installed. It does not allocate any resources and is safe to run and uninstall when you are finished. @@ -181,16 +181,16 @@ $ porter explain ghcr.io/getporter/porter-hello:v0.2.0 Now that you know how to create a bundle, here are some more detailed topics on how to customize and distribute it: -- [Control how your bundle's image is built with a custom Dockerfile](/bundle/custom-dockerfile/) +- [Control how your bundle's image is built with a custom Dockerfile](/docs/bundle/custom-dockerfile/) - [Customize your Porter manifest, porter.yaml][manifest] - [Porter Manifest File Format](/bundle/manifest/file-format/) -- [Best Practices for the exec Mixin](/best-practices/exec-mixin/) -- [Understand how bundles are distributed](/development/authoring-a-bundle/distribute-bundles/) +- [Best Practices for the exec Mixin](/docs/best-practices/exec-mixin/) +- [Understand how bundles are distributed](/docs/development/authoring-a-bundle/distribute-bundles/) [install Porter]: /install/ [Porter Visual Studio Code]: https://marketplace.visualstudio.com/items?itemName=getporter.porter-vscode [hello example bundle]: /examples/hello/ -[manifest]: /bundle/manifest/ +[manifest]: /docs/bundle/manifest/ [local-registry]: https://docs.docker.com/registry/deploying/#run-a-local-registry [porter create]: /cli/porter_create/ [porter build]: /cli/porter_build/ @@ -202,8 +202,8 @@ Now that you know how to create a bundle, here are some more detailed topics on [Mixins]: /mixins/ [create a custom mixin]: /mixin-dev-guide/ [terraform mixin]: /mixins/terraform/ -[do not embed bash commands]: /best-practices/exec-mixin/ +[do not embed bash commands]: /docs/best-practices/exec-mixin/ [ignore-errors]: /blog/ignoring-errors/ [compatible registries]: /compatible-registries/ -[custom Dockerfile]: /bundle/custom-dockerfile/ +[custom Dockerfile]: /docs/bundle/custom-dockerfile/ [Buildkit]: https://docs.docker.com/develop/develop-images/build_enhancements/ diff --git a/docs/content/docs/development/authoring-a-bundle/distribute-bundles.md b/docs/content/docs/development/authoring-a-bundle/distribute-bundles.md index c9690afd0..4f3c22b73 100644 --- a/docs/content/docs/development/authoring-a-bundle/distribute-bundles.md +++ b/docs/content/docs/development/authoring-a-bundle/distribute-bundles.md @@ -147,7 +147,7 @@ Here we can see that the spring-music image was relocated inside the published b `jeremyrickard/spring-music@sha256:8f113...` → `jeremyrickard/porter-do-bundle@sha256:8f113...` -[images]: /author-bundles/#images +[images]: /docs/bundle/manifest/#images ### Archived Bundle Artifacts @@ -163,4 +163,4 @@ ignored: - `jeremyrickard/porter-do-bundle/spring-music` [digest]: https://github.com/opencontainers/image-spec/blob/master/descriptor.md#digests -[image-map]: /author-bundles/#images +[image-map]: /docs/bundle/manifest/#images diff --git a/docs/content/docs/development/authoring-a-bundle/using-templates.md b/docs/content/docs/development/authoring-a-bundle/using-templates.md index d11f468bd..62e9a3b72 100644 --- a/docs/content/docs/development/authoring-a-bundle/using-templates.md +++ b/docs/content/docs/development/authoring-a-bundle/using-templates.md @@ -88,7 +88,7 @@ install: namespace: "myNamespace" ``` -[custom metadata]: /author-bundles/#custom +[custom metadata]: /docs/bundle/manifest/#custom #### parameters @@ -224,7 +224,7 @@ image digest for the specified tag and then update the bundle to reference the i by digest instead of the provided tag. This helps to ensure deterministic and repeatable bundle execution. -[referenced images]: /author-bundles/#images +[referenced images]: /docs/bundle/manifest/#images ### env diff --git a/docs/content/docs/development/authoring-a-bundle/working-with-dependencies.md b/docs/content/docs/development/authoring-a-bundle/working-with-dependencies.md index e9c281980..c7c1b59c2 100644 --- a/docs/content/docs/development/authoring-a-bundle/working-with-dependencies.md +++ b/docs/content/docs/development/authoring-a-bundle/working-with-dependencies.md @@ -194,4 +194,4 @@ transitive dependencies, are ignored. See [Design: Dependency Graph Resolution]( for our backlog item tracking this feature. We do plan to support it! [example]: /src/build/testdata/bundles/wordpress/porter.yaml -[parameter-set]: /parameters#parameter-sets +[parameter-set]: /docs/introduction/concepts-and-components/intro-parameters/#parameter-sets diff --git a/docs/content/docs/development/dist-a-mixin.md b/docs/content/docs/development/dist-a-mixin.md index e616e353b..3e8ae6f2d 100644 --- a/docs/content/docs/development/dist-a-mixin.md +++ b/docs/content/docs/development/dist-a-mixin.md @@ -76,4 +76,4 @@ See the [Search Guide][search-guide] on how to search for available mixins and/o add your own to the list. [mk]: /src/mixin.mk -[search-guide]: /package-search +[search-guide]: /package-search/ diff --git a/docs/content/docs/faq/_index.md b/docs/content/docs/faq/_index.md index a500df3e7..081a4b230 100644 --- a/docs/content/docs/faq/_index.md +++ b/docs/content/docs/faq/_index.md @@ -2,6 +2,8 @@ title: FAQ description: Frequently Asked Questions weight: 16 +aliases: + - /faq/ --- - [What is CNAB?](#what-is-cnab) @@ -96,7 +98,7 @@ standard mechanism defined by the CNAB spec yet. When you create a new bundle, porter generates Dockerfile.tmpl file for you. In the porter.yaml you can specify `dockerfile: dockerfile.tmpl` to tell Porter -that you want to use the template (see [Custom Dockerfile](/bundle/custom-dockerfile/)) and then you can customize +that you want to use the template (see [Custom Dockerfile](/docs/bundle/custom-dockerfile/)) and then you can customize it however you need. You're on the right track, from there you can use the exec mixin to call whatever you installed. diff --git a/docs/content/docs/how-to-guides/_index.md b/docs/content/docs/how-to-guides/_index.md index 3ebb71c69..9dddbb965 100644 --- a/docs/content/docs/how-to-guides/_index.md +++ b/docs/content/docs/how-to-guides/_index.md @@ -9,6 +9,6 @@ aliases: **Guides for working with Mixins and Plugins** {{< cards >}} -{{< card link="work-with-mixins" title="Working with Mixins" >}} -{{< card link="work-with-plugins" title="Working with Plugins" >}} +{{< card link="work-with-mixins/" title="Working with Mixins" >}} +{{< card link="work-with-plugins/" title="Working with Plugins" >}} {{< /cards >}} diff --git a/docs/content/docs/how-to-guides/work-with-plugins.md b/docs/content/docs/how-to-guides/work-with-plugins.md index a59f78a3a..4f9a2fd03 100644 --- a/docs/content/docs/how-to-guides/work-with-plugins.md +++ b/docs/content/docs/how-to-guides/work-with-plugins.md @@ -196,7 +196,7 @@ $ porter credentials apply plugins-tutorial.json Applied /plugins-tutorial credential set ``` -For more information on how to use `porter credentials` commands, take a look at our [credentials quickstart guide](/quickstart/credentials). +For more information on how to use `porter credentials` commands, take a look at our [credentials quickstart guide](/quickstart/credentials/). Now we are ready to install the bundle and pass it our generated credentials. 🎉 Porter is using the Azure plugin to inject the password credential from Azure diff --git a/docs/content/docs/integrations/_index.md b/docs/content/docs/integrations/_index.md index 2a98b02c0..3ca13e1c1 100644 --- a/docs/content/docs/integrations/_index.md +++ b/docs/content/docs/integrations/_index.md @@ -7,8 +7,8 @@ weight: 12 **Learn about various Integrations with Porter** {{< cards >}} -{{< card link="aks" title="Connect to AKS" >}} -{{< card link="gke" title="Connect to GKE" >}} -{{< card link="kind" title="Connect to KinD" >}} -{{< card link="minikube" title="Connect to Minikube" >}} +{{< card link="aks/" title="Connect to AKS" >}} +{{< card link="gke/" title="Connect to GKE" >}} +{{< card link="kind/" title="Connect to KinD" >}} +{{< card link="minikube/" title="Connect to Minikube" >}} {{< /cards >}} diff --git a/docs/content/docs/integrations/gke.md b/docs/content/docs/integrations/gke.md index caefbc397..d9594d04d 100644 --- a/docs/content/docs/integrations/gke.md +++ b/docs/content/docs/integrations/gke.md @@ -32,7 +32,7 @@ See [ghcr.io/getporter/examples/gke][example] for a full working example bundle. recommended over using a parameter. Using parameters to define environment variables is a hack provided only for the purpose of this example. - - Add the following line to your [Custom Dockerfile](/bundle/custom-dockerfile): + - Add the following line to your [Custom Dockerfile](/docs/bundle/custom-dockerfile/): ``` ENV GOOGLE_APPLICATION_CREDENTIALS=/home/nonroot/google-service-account.json diff --git a/docs/content/docs/integrations/kind.md b/docs/content/docs/integrations/kind.md index c6ccd50ef..9b5f33bf3 100644 --- a/docs/content/docs/integrations/kind.md +++ b/docs/content/docs/integrations/kind.md @@ -54,7 +54,7 @@ To further debug and diagnose cluster problems, use 'kubectl cluster-info dump'. ### Porter time! -Porter bundles that access a Kubernetes cluster when running can now be installed as normal, once the [Credential Set](/references/file-formats/credential-set/) is generated/edited to use the KinD kubeconfig. +Porter bundles that access a Kubernetes cluster when running can now be installed as normal, once the [Credential Set](/docs/references/file-formats/credential-set/) is generated/edited to use the KinD kubeconfig. Here we'll create and edit credentials and then install the [MySQL bundle](/src/build/testdata/bundles/mysql): diff --git a/docs/content/docs/introduction/_index.md b/docs/content/docs/introduction/_index.md index 753830eb4..bf4045983 100644 --- a/docs/content/docs/introduction/_index.md +++ b/docs/content/docs/introduction/_index.md @@ -7,6 +7,6 @@ weight: 1 **Start learning about Porter today** {{< cards >}} -{{< card link="what-is-porter" title="What is Porter?" >}} -{{< card link="concepts-and-components" title="Concepts and Components" >}} +{{< card link="what-is-porter/" title="What is Porter?" >}} +{{< card link="concepts-and-components/" title="Concepts and Components" >}} {{< /cards >}} diff --git a/docs/content/docs/introduction/concepts-and-components/_index.md b/docs/content/docs/introduction/concepts-and-components/_index.md index e77042d10..9859c2632 100644 --- a/docs/content/docs/introduction/concepts-and-components/_index.md +++ b/docs/content/docs/introduction/concepts-and-components/_index.md @@ -6,13 +6,13 @@ description: "" **Learn about all the different Concepts and Components** {{< cards >}} -{{< card link="intro-bundles" title="Bundles" >}} -{{< card link="intro-parameters" title="Parameters" >}} -{{< card link="intro-configuration" title="Configuration" >}} -{{< card link="intro-credentials" title="Credentials" >}} -{{< card link="intro-desired-state" title="Desired State" >}} -{{< card link="intro-invocation-images" title="Invocation Images" >}} -{{< card link="intro-mixins" title="Mixins" >}} -{{< card link="mixins-vs-plugins" title="Mixins vs Plugins" >}} -{{< card link="intro-plugins" title="Plugins" >}} +{{< card link="intro-bundles/" title="Bundles" >}} +{{< card link="intro-parameters/" title="Parameters" >}} +{{< card link="intro-configuration/" title="Configuration" >}} +{{< card link="intro-credentials/" title="Credentials" >}} +{{< card link="intro-desired-state/" title="Desired State" >}} +{{< card link="intro-invocation-images/" title="Invocation Images" >}} +{{< card link="intro-mixins/" title="Mixins" >}} +{{< card link="mixins-vs-plugins/" title="Mixins vs Plugins" >}} +{{< card link="intro-plugins/" title="Plugins" >}} {{< /cards >}} diff --git a/docs/content/docs/introduction/concepts-and-components/intro-configuration.md b/docs/content/docs/introduction/concepts-and-components/intro-configuration.md index 916b94c21..dfd0ee019 100644 --- a/docs/content/docs/introduction/concepts-and-components/intro-configuration.md +++ b/docs/content/docs/introduction/concepts-and-components/intro-configuration.md @@ -224,7 +224,7 @@ Use the trace and logs configuration sections below to configure how logs and te #### Logs -Porter can be configured to [write a logfile for each command](/administrators/diagnostics/#logs). +Porter can be configured to [write a logfile for each command](/docs/administration/collect-diag-porter/#logs). The following log settings are available: @@ -274,7 +274,7 @@ telemetry: ### Dependencies v2 The `dependencies-v2` experimental flag is not yet implemented. -When it is completed, it is used to activate the features from [PEP003 - Advanced Dependencies](https://github.com/getporter/proposals/blob/main/pep/003-dependency-namespaces-and-labels.md). +When it is completed, it is used to activate the features from [PEP003 - Advanced Dependencies](https://github.com/getporter/proposals/blob/main/pep/003-advanced-dependencies.md). ### Full control Dockerfile diff --git a/docs/content/docs/introduction/concepts-and-components/intro-mixins.md b/docs/content/docs/introduction/concepts-and-components/intro-mixins.md index 045bf1e10..bba636de9 100644 --- a/docs/content/docs/introduction/concepts-and-components/intro-mixins.md +++ b/docs/content/docs/introduction/concepts-and-components/intro-mixins.md @@ -17,13 +17,13 @@ Only the [exec mixin](/mixins/exec/) is installed by default. # Next -- [Use a mixin in a bundle](/author-bundles/#mixins) +- [Use a mixin in a bundle](/docs/bundle/manifest/#images) - [Mixin Architecture](/how-to-guides/work-with-mixins/) # Available Mixins Below are mixins that are either maintained by the Porter authors, or are community mixins that are known to be well-maintained. -Use the [porter mixins search](/cli/porter_mixins_search) command to see all known mixins. +Use the [porter mixins search](/cli/porter_mixins_search/) command to see all known mixins. See the [Search Guide][search-guide] on how to search for available plugins and/or add your own to the list. diff --git a/docs/content/docs/introduction/concepts-and-components/intro-parameters.md b/docs/content/docs/introduction/concepts-and-components/intro-parameters.md index d5f3decde..e7d63c086 100644 --- a/docs/content/docs/introduction/concepts-and-components/intro-parameters.md +++ b/docs/content/docs/introduction/concepts-and-components/intro-parameters.md @@ -40,10 +40,10 @@ can have a secret source (`secret`). See the [secrets plugin docs](/plugins/types/#secrets) to learn how to configure Porter to use an external secret store. -Parameter Sets are created using the combination of [porter parameters create](/docs/references/cli/parameters/create) -and [porter parameters apply](/docs/references/cli/parameters/apply). -Afterwards a parameter set can be [edited](/docs/references/cli/parameters/edit) if changes are required. -See [porter parameters help](/docs/references/cli/parameters) for all available commands. +Parameter Sets are created using the combination of [porter parameters create](/cli/porter_parameters_create/) +and [porter parameters apply](/cli/porter_parameters_apply/). +Afterwards a parameter set can be [edited](/cli/porter_parameters_edit/) if changes are required. +See [porter parameters help](/cli/porter_parameters/) for all available commands. Now when you execute the bundle you can pass the name of the parameter set to the command using the `--parameter-set` or `-p` flag, e.g. @@ -83,9 +83,9 @@ the [Author Bundles](/docs/bundle/manifest/) doc for more info. See the helpful explanation in the [credentials](/docs/introduction/concepts-and-components/intro-credentials/) doc, which applies to parameter sources as well. -[create]: /docs/references/cli/parameters_create/ -[apply]: /docs/references/cli/parameters_apply/ -[edit]: /docs/references/cli/parameters_edit/ +[create]: /cli/porter_parameters_create/ +[apply]: /cli/porter_parameters_apply/ +[edit]: /cli/porter_parameters_edit/ ## Related diff --git a/docs/content/docs/operations/_index.md b/docs/content/docs/operations/_index.md index 308ffe90c..fbaac0794 100644 --- a/docs/content/docs/operations/_index.md +++ b/docs/content/docs/operations/_index.md @@ -7,10 +7,10 @@ weight: 5 **Get Started with Porter** {{< cards >}} -{{< card link="manage-installations" title="Manage Installations" >}} -{{< card link="examine-bundles" title="Examine Bundles" >}} -{{< card link="view-logs" title="View Logs" >}} -{{< card link="create-porter-config" title="Create a Porter Config File" >}} -{{< card link="connect-to-docker" title="Connect to Docker" >}} -{{< card link="connect-to-registry" title="Connect to Registry" >}} +{{< card link="manage-installations/" title="Manage Installations" >}} +{{< card link="examine-bundles/" title="Examine Bundles" >}} +{{< card link="view-logs/" title="View Logs" >}} +{{< card link="create-porter-config/" title="Create a Porter Config File" >}} +{{< card link="connect-to-docker/" title="Connect to Docker" >}} +{{< card link="connect-to-registry/" title="Connect to Registry" >}} {{< /cards >}} diff --git a/docs/content/docs/operations/create-porter-config.md b/docs/content/docs/operations/create-porter-config.md index 6e51b9b25..15d88bc7a 100644 --- a/docs/content/docs/operations/create-porter-config.md +++ b/docs/content/docs/operations/create-porter-config.md @@ -16,24 +16,24 @@ configurations, so you don't need to repeat them each time when you run porter. The configuration file should be stored in the PORTER_HOME directory, by default ~/.porter/. In the example below, we are going to use the yaml format, however, porter supports other file formats for its config file as well. For more detailed -information, please see [configuration](/configuration/#config-file). +information, please see [configuration](/docs/configuration/configuration/#config-file). Create a file at ~/.porter/config.yaml and open it in your editor. ## Configure Plugins -By default, Porter uses the [host plugin](/plugins/host) for resolving secrets and the [mongodb-docker](/plugins/mongodb-docker) as the storage +By default, Porter uses the [host plugin](/plugins/host/) for resolving secrets and the [mongodb-docker](/plugins/mongodb-docker/) as the storage plugin. In the examples below, we will see how to configure Porter to use other plugins. ### Change the default secrets plugin The default host plugin does not provide the functionality to work with bundles that work with sensitive data. -Next, configure Porter to use the [filesystem](/plugins/filesystem) as the secret plugin so that you can work with sensitive data. +Next, configure Porter to use the [filesystem](/plugins/filesystem/) as the secret plugin so that you can work with sensitive data. The filesystem plugin stores secrets in your PORTER_HOME directory. It is suitable for trying out Porter, and local development and testing, but should not be used in production. Once you have the [newly created config file](#create-a-config-file), open in your choice of editor, -change the default secret plugin to [filesystem](/plugins/filesystem): +change the default secret plugin to [filesystem](/plugins/filesystem/): ```yaml default-secrets-plugin: "filesystem" @@ -41,8 +41,8 @@ default-secrets-plugin: "filesystem" After saving this change to the config file, you will be able to work with bundles that contains sensitive parameters or outputs on your local machine. Be -aware that the [filesystem](/plugins/filesystem) stores sensitive data in plaintext on your filesystem. -Use either the [azure-keyvault](/plugins/azure-keyvault) or [hashicorp-vault](/plugins/hashicorp-vault) plugin in production. +aware that the [filesystem](/plugins/filesystem/) stores sensitive data in plaintext on your filesystem. +Use either the [azure-keyvault](/plugins/azure-keyvault/) or [hashicorp-vault](/plugins/hashicorp-vault/) plugin in production. ### Change the default storage plugin @@ -68,5 +68,5 @@ suitable for production use. ## Next Steps -- [Configuration File Format](/configuration/) -- [Available Plugins](/plugins/#available-plugins) +- [Configuration File Format](/docs/configuration/configuration/) +- [Available Plugins](/plugins/) diff --git a/docs/content/docs/operations/examine-bundles.md b/docs/content/docs/operations/examine-bundles.md index dead4428a..e025cb730 100644 --- a/docs/content/docs/operations/examine-bundles.md +++ b/docs/content/docs/operations/examine-bundles.md @@ -39,4 +39,4 @@ The `porter explain` command will show what credentials and parameters are requi `porter explain` can be used with a published bundle, as show above, or with a local bundle. The command even works with bundles that were not built with Porter, through the use of the `--cnab-file` flag. For all the options, run the command `porter explain --help`. -If you would like to see the invocation images and/or the images the bundle will use, see the [inspect](/inspect-bundles) command. +If you would like to see the invocation images and/or the images the bundle will use, see the [inspect](/cli/inspect-bundles/) command. diff --git a/docs/content/docs/operations/manage-installations.md b/docs/content/docs/operations/manage-installations.md index 8d0881cd5..8b3bc8458 100644 --- a/docs/content/docs/operations/manage-installations.md +++ b/docs/content/docs/operations/manage-installations.md @@ -74,4 +74,4 @@ With a GitOps workflow, you define the desired state of your applications and in [porter upgrade]: /cli/porter_upgrade/ [porter uninstall]: /cli/porter_uninstall/ [porter installation apply]: /cli/porter_installations_apply/ -[Porter Operator]: /operator/ +[Porter Operator]: /docs/operator/ diff --git a/docs/content/docs/quickstart/_index.md b/docs/content/docs/quickstart/_index.md index 48b7d6559..36a8f0d46 100644 --- a/docs/content/docs/quickstart/_index.md +++ b/docs/content/docs/quickstart/_index.md @@ -120,8 +120,8 @@ $ porter uninstall porter-hello Now you've seen the basics to install, upgrade or uninstall a bundle. From here, you can dive into what a bundle is - or create your own! -- [Next: What is a Bundle?](/quickstart/bundles/) -- [Next: Create my own bundle](/getting-started/create-a-bundle/) -- [Learn more about use cases for bundles](/learning/#the-devil-is-in-the-deployments-bundle-use-cases) +- [Next: What is a Bundle?](/docs/quickstart/bundles/) +- [Next: Create my own bundle](/docs/getting-started/create-bundle/) +- [Learn more about use cases for bundles](/docs/learn/#the-devil-is-in-the-deployments-bundle-use-cases) diff --git a/docs/content/docs/quickstart/bundles.md b/docs/content/docs/quickstart/bundles.md index 2dde5dcaa..f9ee21675 100644 --- a/docs/content/docs/quickstart/bundles.md +++ b/docs/content/docs/quickstart/bundles.md @@ -13,7 +13,7 @@ For this quickstart, the main concepts that you will use include: - Installation - An instance of a bundle installed to your system. - Tag - A reference to the bundle in an [OCI](https://opencontainers.org/) registry that contains the registry, bundle name, and version, e.g. myregistry.com/mybundle:v1.0. - Registry - An OCI compliant artifact store. - Many Docker registries are now OCI compliant and work with bundles, here's a list of [popular registries have been tested with Porter](/references/compatible-registries). + Many Docker registries are now OCI compliant and work with bundles, here's a list of [popular registries have been tested with Porter](/docs/references/compatible-registries/). ## Understand a Bundle @@ -125,5 +125,5 @@ A bundle, as defined by the CNAB specification, is a standard packaging format f Create your own bundle, or learn more! -- [Next: Create your own bundle](/getting-started/create-bundle/) -- [Learn more about use cases for bundles](/learning/#the-devil-is-in-the-deployments-bundle-use-cases) +- [Next: Create your own bundle](/docs/getting-started/create-bundle/) +- [Learn more about use cases for bundles](/docs/learn/#the-devil-is-in-the-deployments-bundle-use-cases) diff --git a/docs/content/docs/quickstart/configuration.md b/docs/content/docs/quickstart/configuration.md index 38a90e2bc..8a5ff6a3a 100644 --- a/docs/content/docs/quickstart/configuration.md +++ b/docs/content/docs/quickstart/configuration.md @@ -49,7 +49,7 @@ default-secrets-plugin: "filesystem" This enables the filesystem secret plugin to store any sensitive parameters provided by users, or sensitive outputs generated by bundles. The filesystem plugin should not be used in production environments since data -is stored as plain text in Porter's home directory. Please use either the [azure-keyvault](/plugins/azure#secrets) +is stored as plain text in Porter's home directory. Please use either the [azure-keyvault](/plugins/azure/#secrets) or [hashicorp-vault](/plugins/hashicorp/#plugin-configuration) plugin for production. ## Next Steps @@ -58,4 +58,4 @@ In this QuickStart you learned how to configure Porter to define global default value for bundles and porter itself. You also learned how to work with bundles that contains or produces sensitive data. -- [Learn more about Porter's configuration file](/configuration) +- [Learn more about Porter's configuration file](/configuration/) diff --git a/docs/content/docs/quickstart/desired-state.md b/docs/content/docs/quickstart/desired-state.md index 4f3a24191..0dbe1237d 100644 --- a/docs/content/docs/quickstart/desired-state.md +++ b/docs/content/docs/quickstart/desired-state.md @@ -297,11 +297,11 @@ The installation is out-of-sync, running the uninstall action... In this QuickStart you learned how to manage installations using desired state by defining the installation in a file, and then triggering reconciliation of that installation with the apply command. -- [Understand the difference between imperative commands and desired state](/operations/manage-installations/) -- [Automating Porter with the Porter Operator](/operator/) +- [Understand the difference between imperative commands and desired state](/docs/operations/manage-installations/) +- [Automating Porter with the Porter Operator](/docs/operator/) - [Create a bundle](/development/create-a-bundle/) -[managing installations]: /operations/manage-installations/ +[managing installations]: /docs/operations/manage-installations/ [porter credentials apply]: /cli/porter_credentials_apply/ [porter parameters apply]: /cli/porter_parameters_apply/ [porter installation apply]: /cli/porter_installations_apply/ diff --git a/docs/content/docs/quickstart/parameters.md b/docs/content/docs/quickstart/parameters.md index 3035e73a3..b7cef4cf6 100644 --- a/docs/content/docs/quickstart/parameters.md +++ b/docs/content/docs/quickstart/parameters.md @@ -91,7 +91,7 @@ execution completed successfully! ## Create a Parameter Set -Create a parameter set for the hello-llama with the combination of `porter parameters create` and `porter parameters apply` commands. The `create` command will generate a [template file](/reference/file-formats#parameter-set). You need to edit the file to include the corresponding parameters needed for the bundle. After modifying the file, the `apply` command will create the parameter set based on the file. +Create a parameter set for the hello-llama with the combination of `porter parameters create` and `porter parameters apply` commands. The `create` command will generate a [template file](/docs/references/file-formats/parameter-set/). You need to edit the file to include the corresponding parameters needed for the bundle. After modifying the file, the `apply` command will create the parameter set based on the file. ```console $ porter parameters create hello-llama.json diff --git a/docs/content/docs/references/docker-images/_index.md b/docs/content/docs/references/docker-images/_index.md index 2d8374796..b18f1147f 100644 --- a/docs/content/docs/references/docker-images/_index.md +++ b/docs/content/docs/references/docker-images/_index.md @@ -9,6 +9,6 @@ you for your CI pipelines and in other situations where you can't install Porter locally, such as workshops. {{< cards >}} -{{< card link="agent" title="Porter Agent Docker Image" >}} -{{< card link="client" title="Porter Client Docker Image" >}} +{{< card link="agent/" title="Porter Agent Docker Image" >}} +{{< card link="client/" title="Porter Client Docker Image" >}} {{< /cards >}} diff --git a/docs/content/docs/references/docker-images/agent.md b/docs/content/docs/references/docker-images/agent.md index 223ab545f..489643177 100644 --- a/docs/content/docs/references/docker-images/agent.md +++ b/docs/content/docs/references/docker-images/agent.md @@ -28,9 +28,142 @@ Run the following command to run the porter-hello bundle on a cluster to try it kubectl apply -f https://raw.githubusercontent.com/getporter/porter/a059a9668934dff475f9d9633781d2f32512581d/examples/porter-agent-manifest.yaml ``` - +```yaml +apiVersion: v1 +kind: Namespace +metadata: + name: porter-agent-test +--- +apiVersion: rbac.authorization.k8s.io/v1 +kind: Role +metadata: + name: porter-agent-role + namespace: porter-agent-test +rules: +- apiGroups: + - "" + resources: + - pods + - namespaces + verbs: + - get + - list + - watch +- apiGroups: + - "" + resources: + - pods/log + verbs: + - get + - list +- apiGroups: + - "" + resources: + - secrets + verbs: + - create + - delete + - get + - list + - watch +- apiGroups: + - batch + resources: + - jobs + verbs: + - create + - delete + - get + - list + - patch + - update + - watch +--- +apiVersion: v1 +kind: ServiceAccount +metadata: + name: porter-agent + namespace: porter-agent-test +--- +apiVersion: rbac.authorization.k8s.io/v1 +kind: RoleBinding +metadata: + name: porter-agent + namespace: porter-agent-test +roleRef: + apiGroup: rbac.authorization.k8s.io + kind: Role + name: porter-agent-role +subjects: +- kind: ServiceAccount + name: porter-agent + namespace: porter-agent-test +--- +apiVersion: v1 +kind: PersistentVolumeClaim +metadata: + name: porter-hello-shared + namespace: porter-agent-test +spec: + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 64Mi +--- +apiVersion: v1 +kind: Pod +metadata: + name: porter-hello-3591 + namespace: porter-agent-test +spec: + containers: + - args: + - install + - porter-hello + - --reference=getporter/porter-hello:v0.1.1 + - --driver=kubernetes + env: + - name: KUBE_NAMESPACE + value: porter-agent-test + - name: IN_CLUSTER + value: "true" + - name: LABELS + value: porter=true installation=porter-hello installation-version=3591 + - name: JOB_VOLUME_NAME + value: porter-hello-shared + - name: JOB_VOLUME_PATH + value: /porter-shared + - name: CLEANUP_JOBS + value: "true" + - name: SERVICE_ACCOUNT + - name: AFFINITY_MATCH_LABELS + value: installation=porter-hello installation-version=3591 + envFrom: + - secretRef: + name: porter-env + optional: true + image: getporter/porter-agent:latest + name: porter-hello-3591 + resources: {} + volumeMounts: + - mountPath: /porter-shared + name: porter-shared + - mountPath: /porter-config + name: porter-config + serviceAccountName: porter-agent + volumes: + - name: porter-shared + persistentVolumeClaim: + claimName: porter-hello-shared + - name: porter-config + secret: + defaultMode: 420 + optional: true + secretName: porter-config +``` -[configuration]: /configuration +[configuration]: /docs/configuration/configuration/ [porter-agent]: https://github.com/getporter/porter/pkgs/container/porter-agent -[porter client]: /references/docker-images/client/ +[porter client]: /docs/references/docker-images/client/ [Porter Operator]: https://github.com/getporter/operator diff --git a/docs/content/docs/references/examples/airgap.md b/docs/content/docs/references/examples/airgap.md index 1abbaf368..6adae2149 100644 --- a/docs/content/docs/references/examples/airgap.md +++ b/docs/content/docs/references/examples/airgap.md @@ -83,7 +83,7 @@ The helm chart must have been written to allow specifying the location of any im Then in your install step, use the helm \--set flag overriding the image with its location in the airgapped environment. Porter handles tracking the image location for you, just use the template variables to swap the image used by the helm chart. -[images]: /author-bundles/#images +[images]: /docs/bundle/manifest/#images ## Move the bundle across the airgap diff --git a/docs/content/docs/references/examples/docker.md b/docs/content/docs/references/examples/docker.md index ec4d76623..d17d303cb 100644 --- a/docs/content/docs/references/examples/docker.md +++ b/docs/content/docs/references/examples/docker.md @@ -58,7 +58,7 @@ The user running the bundle, and Porter, needs to know that this bundle requires the local Docker daemon connected to the bundle. We have added a new section to porter.yaml for required extensions, and defined a new prototype extension that says that the bundle [requires access to a Docker -daemon](/author-bundles/#docker): +daemon](/docs/bundle/manifest/#docker): ```yaml required: @@ -99,7 +99,63 @@ install: In my porter.yaml, I can use the docker mixin to execute docker commands in my bundle: - +```yaml +schemaVersion: 1.0.0-alpha.1 +name: examples/whalesay +version: 0.2.0 +description: "An example bundle that uses docker through the magic of whalespeak" +registry: ghcr.io/getporter + +required: + - docker + +parameters: + - name: msg + description: a message for the whales to speak + type: string + default: "whale hello there!" + applyTo: + - say + +mixins: + - docker + +install: + - docker: + run: + image: "docker/whalesay:latest" + rm: true + arguments: + - cowsay + - Hello World + +upgrade: + - docker: + run: + image: "docker/whalesay:latest" + rm: true + arguments: + - cowsay + - World 2.0 + +say: + - docker: + run: + image: "docker/whalesay:latest" + rm: true + arguments: + - cowsay + - "{{ bundle.parameters.msg }}" + +uninstall: + - docker: + run: + image: "docker/whalesay:latest" + rm: true + arguments: + - cowsay + - Goodbye World +``` After I have tested the bundle, I used `porter publish` to push it up to `ghcr.io/getporter/examples/whalesay:v0.2.0`. @@ -107,7 +163,7 @@ After I have tested the bundle, I used `porter publish` to push it up to `ghcr.i Now that the bundle is ready to use, the user running the bundle needs to give the bundle elevated permission with the [Allow Docker Host -Access](/configuration/#allow-docker-host-access) setting. This +Access](/docs/configuration/configuration/#allow-docker-host-access) setting. This is because giving a container access to the host's Docker socket, or running a container with `--privileged`, has security implications for the underlying host, and should only be given to trusted containers, or in this case trusted bundles. diff --git a/docs/content/docs/references/file-formats/_index.md b/docs/content/docs/references/file-formats/_index.md index 4d2d3140e..7479b2102 100644 --- a/docs/content/docs/references/file-formats/_index.md +++ b/docs/content/docs/references/file-formats/_index.md @@ -11,4 +11,4 @@ aliases: - [Parameter Sets](./parameter-set/) - [Installation](./installation/) - [Plugins](./plugins/) -- [Porter Operator File Formats](/operator/file-formats/) +- [Porter Operator File Formats](/docs/operator/file-formats/) diff --git a/docs/content/docs/references/file-formats/credential-set/_index.md b/docs/content/docs/references/file-formats/credential-set/_index.md index a86f14455..e0cb10130 100644 --- a/docs/content/docs/references/file-formats/credential-set/_index.md +++ b/docs/content/docs/references/file-formats/credential-set/_index.md @@ -19,7 +19,7 @@ Below are schema versions for credential sets, and the corresponding Porter vers Sometimes you may want to work with a different version of a resource than what is supported by Porter, especially when migrating from one version of Porter to another. The [schema-check] configuration setting allows you to change how Porter behaves when the schemaVersion of a resource doesn't match Porter's supported version. -[schema-check]: /configuration/#schema-check +[schema-check]: /docs/configuration/configuration/#schema-check ## Example diff --git a/docs/content/docs/references/file-formats/installation/_index.md b/docs/content/docs/references/file-formats/installation/_index.md index 0e144f413..5b32ff8c5 100644 --- a/docs/content/docs/references/file-formats/installation/_index.md +++ b/docs/content/docs/references/file-formats/installation/_index.md @@ -18,7 +18,7 @@ Below are schema versions for installations, and the corresponding Porter versio Sometimes you may want to work with a different version of a resource than what is supported by Porter, especially when migrating from one version of Porter to another. The [schema-check] configuration setting allows you to change how Porter behaves when the schemaVersion of a resource doesn't match Porter's supported version. -[schema-check]: /configuration/#schema-check +[schema-check]: /docs/configuration/configuration/#schema-check ## Example diff --git a/docs/content/docs/references/file-formats/parameter-set/_index.md b/docs/content/docs/references/file-formats/parameter-set/_index.md index 6e0508968..fb5f8e8c5 100644 --- a/docs/content/docs/references/file-formats/parameter-set/_index.md +++ b/docs/content/docs/references/file-formats/parameter-set/_index.md @@ -19,7 +19,7 @@ Below are schema versions for parameter sets, and the corresponding Porter versi Sometimes you may want to work with a different version of a resource than what is supported by Porter, especially when migrating from one version of Porter to another. The [schema-check] configuration setting allows you to change how Porter behaves when the schemaVersion of a resource doesn't match Porter's supported version. -[schema-check]: /configuration/#schema-check +[schema-check]: /docs/configuration/configuration/#schema-check ## Example diff --git a/docs/content/docs/references/file-formats/plugins/_index.md b/docs/content/docs/references/file-formats/plugins/_index.md index fc7ac4466..592836bf7 100644 --- a/docs/content/docs/references/file-formats/plugins/_index.md +++ b/docs/content/docs/references/file-formats/plugins/_index.md @@ -21,7 +21,7 @@ Below are schema versions for plugin installation files, and the corresponding P Sometimes you may want to work with a different version of a resource than what is supported by Porter, especially when migrating from one version of Porter to another. The [schema-check] configuration setting allows you to change how Porter behaves when the schemaVersion of a resource doesn't match Porter's supported version. -[schema-check]: /configuration/#schema-check +[schema-check]: /docs/configuration/configuration/#schema-check ## Changes diff --git a/docs/content/docs/references/library/_index.md b/docs/content/docs/references/library/_index.md index ca3da94af..0cffd20bb 100644 --- a/docs/content/docs/references/library/_index.md +++ b/docs/content/docs/references/library/_index.md @@ -22,8 +22,85 @@ We recommend using the `porter.Porter` struct, which is created by `porter.New()` when automating Porter. There are more functions and packages exposed, but those are much more likely to change over time. - +```go +package examples_test + +import ( + "context" + "fmt" + "log" + + "get.porter.sh/porter/pkg/porter" +) + +func ExamplePorter_install() { + // Create an instance of the Porter application + p := porter.New() + + // Specify any of the command-line arguments to pass to the install command + installOpts := porter.NewInstallOptions() + // install a bundle with older cnab bundle schema version. It should succeed + installOpts.Reference = "ghcr.io/getporter/examples/porter-hello:v0.2.0" + + // Always call validate on the options before executing. There is defaulting + // logic in the Validate calls. + const installationName = "porter-hello" + err := installOpts.Validate(context.Background(), []string{installationName}, p) + if err != nil { + log.Fatal(err) + } + + // porter install porter-hello --reference ghcr.io/getporter/examples/porter-hello:v0.2.0 + err = p.InstallBundle(context.Background(), installOpts) + if err != nil { + log.Fatal(err) + } + + // Get the bundle's status after installing. + showOpts := porter.ShowOptions{} + err = showOpts.Validate([]string{installationName}, p.Context) + if err != nil { + log.Fatal(err) + } + + installation, _, err := p.GetInstallation(context.Background(), showOpts) + if err != nil { + log.Fatal(err) + } + + fmt.Println(installation.Status) +} +``` If you need to set stdin/stdout/stderr, you can set `Porter.Out`. The example below demonstrates how to capture stdout. - +```go +package examples_test + +import ( + "bytes" + "context" + "fmt" + "log" + + "get.porter.sh/porter/pkg/porter" +) + +func ExamplePorter_captureOutput() { + // Create an instance of the Porter application + p := porter.New() + + // Save output to a buffer + output := bytes.Buffer{} + p.Out = &output + + // porter schema + err := p.PrintManifestSchema(context.Background()) + if err != nil { + log.Fatal(err) + } + + // Print the json schema for porter + fmt.Println(output.String()) +} +``` diff --git a/docs/content/docs/references/linter.md b/docs/content/docs/references/linter.md index 408e75ecf..55e0ee667 100644 --- a/docs/content/docs/references/linter.md +++ b/docs/content/docs/references/linter.md @@ -19,7 +19,7 @@ Using embedded Bash scripts can be problematic because they can be difficult to To fix the problem indicated by the exec-100 warning, you can try replacing any embedded Bash scripts in your exec mixins with scripts. -You can find more information about best practices for using the exec mixin on the Porter website at the following URL: https://porter.sh/best-practices/exec-mixin/#use-scripts. +You can find more information about best practices for using the exec mixin on the Porter website at the following URL: https://porter.sh(/docs/best-practices/exec-mixin/)#use-scripts. ## porter-100 diff --git a/docs/content/docs/troubleshooting/_index.md b/docs/content/docs/troubleshooting/_index.md index e50b3b149..b070d3cfe 100644 --- a/docs/content/docs/troubleshooting/_index.md +++ b/docs/content/docs/troubleshooting/_index.md @@ -12,7 +12,7 @@ With any porter error, it can really help to re-run the command again with the ` ## Examine Previous Logs -Porter [saves the logs](/operations/view-logs/) when a bundle is executed. Comparing the logs +Porter [saves the logs](/docs/operations/view-logs/) when a bundle is executed. Comparing the logs from a failing run to those from a successful run may assist with troubleshooting. diff --git a/docs/content/mixin-dev-guide/commands.md b/docs/content/mixin-dev-guide/commands.md index 7f5a29902..2543a2611 100644 --- a/docs/content/mixin-dev-guide/commands.md +++ b/docs/content/mixin-dev-guide/commands.md @@ -13,17 +13,16 @@ you are writing a mixin in Go, we strongly recommend starting from the template. **Required Commands** -- [build](#build) -- [schema](#schema) -- [install](#install) -- [upgrade](#upgrade) -- [uninstall](#uninstall) +* [build](#build) +* [schema](#schema) +* [install](#install) +* [upgrade](#upgrade) +* [uninstall](#uninstall) **Optional Commands** * [invoke](#invoke) - ## build The build command (required) is called on the local machine during the `porter diff --git a/docs/content/mixins/exec.md b/docs/content/mixins/exec.md index 74d3407ad..9a31cc5d8 100644 --- a/docs/content/mixins/exec.md +++ b/docs/content/mixins/exec.md @@ -5,7 +5,7 @@ description: Run a command or script Run a command or script. -✅ Learn how to use the exec mixin with our [Exec Mixin Best Practice Guide](/docs/best-practices/exec-mixin/) +✅ Learn how to use the exec mixin with our [Exec Mixin Best Practice Guide](/docs(/docs/best-practices/exec-mixin/)) Source: https://porter.sh/src/pkg/exec diff --git a/tests/integration/testdata/bundles/exec-outputs/README.md b/tests/integration/testdata/bundles/exec-outputs/README.md index 93e13da74..1ca1a7c91 100644 --- a/tests/integration/testdata/bundles/exec-outputs/README.md +++ b/tests/integration/testdata/bundles/exec-outputs/README.md @@ -3,4 +3,4 @@ This bundle demonstrates how to use outputs with the exec mixin. Most mixins are based on the exec mixin, so you can use what you learn here with them. -It also demonstrates how to use a [helper script with the exec mixin](https://porter.sh/best-practices/exec-mixin/#use-scripts). \ No newline at end of file +It also demonstrates how to use a [helper script with the exec mixin](https://porter.sh(/docs/best-practices/exec-mixin/)#use-scripts). \ No newline at end of file