Update docs: build secrets moved from pro-plugin to faas-cli

- Remove pro-plugin references from build secrets docs, use faas-cli
  build/publish directly
- Update remote builder docs: build_secrets values are now file paths,
  not literal values
- Add build_secrets section to YAML reference

Signed-off-by: Han Verstraete (OpenFaaS Ltd) <han@openfaas.com>

Author: welteki

docs/cli/build.md

@@ -20,34 +20,21 @@ When it comes to continuous integration and delivery you can use the `faas-cli`
 
 If you are using an alternative container image builder or are automating the `faas-cli` then you can use the `--shrinkwrap` flag which will produce a folder named `./build/function-name` with a Dockerfile. This bundle can be used with any container builder.
 
-## Plugins and build-time secrets
+## Build-time secrets
 
-!!! info "Experimental feature"
-
-    This is an experimental feature which means that it may change in the future.
-
-When using Docker's buildkit project to build your containers, faas-cli can pass in the arguments to mount different secrets into the build process.
-
-Any other mechanism should be considered insecure because it will leak into the final image or the local image in one way or another.
+When using Docker's BuildKit to build your containers, `faas-cli` can mount secrets into the build process using Docker's `--secret` flag. This prevents sensitive values from leaking into the final image, which can happen when using `--build-arg`.
 
 For Go users, make use of vendoring. It's what we use and it means you do not have to resort to insecure practices like sharing Personal Access Tokens (PAT) between users.
 
 Below we have an example for Python using the pip package manager and for node modules with npm. The approach is similar for different package managers.
 
-1. Download and enable the OpenFaaS Pro plugin
-2. Create a local file in the format required
-3. Update a `build_secret` in `stack.yml` so it gets mounted into the container
-4. Run `faas-cli pro build` or `faas-cli pro publish`, `faas-cli pro up` is not available at this time
+1. Create a local file containing the secret value
+2. Add a `build_secrets` entry in `stack.yml` pointing to the file path
+3. Use `RUN --mount=type=secret` in the Dockerfile to access the secret at build time
+4. Run `faas-cli build` or `faas-cli publish`
 
 ### Private access to a Python pip repository
 
-First enable OpenFaaS Pro:
-
-```bash
-faas-cli plugin get pro
-faas-cli pro enable
-```
-
 Download the OpenFaaS Pro template using your customer credentials:
 
 ```bash
@@ -93,29 +80,10 @@ index-url = https://aws:CODEARTIFACT_TOKEN@OWNER-DOMAIN.d.codeartifact.us-east-1
 Then run a build with:
 
 ```bash
-faas-cli pro build
+faas-cli build
 ```
 
-The `faas-cli pro publish` command can also be used instead of `faas-cli pro build`.
-
-Within a GitHub Action, the short-lived token associated to the job is used to verify your license for this feature.
-
-Add to your workflow.yaml:
-
-```yaml
-    permissions:
-      contents: 'read'
-      id-token: 'write'
-```
-
-Then:
-
-```bash
-faas-cli plugin get pro
-faas-cli pro enable
-
-faas-cli pro build / publish
-```
+The `faas-cli publish` command can also be used instead of `faas-cli build`.
 
 If you're cloning from a private Git repository, without using a private PyPi repository, then you can use the `.netrc` approach instead:
 
@@ -141,13 +109,6 @@ Bear in mind that at this time, `GITHUB_TOKEN` in a GitHub Action cannot be used
 
 ### Private npm modules
 
-Get the OpenFaaS Pro plugin and enable it:
-
-```bash
-faas-cli plugin get pro
-faas-cli pro enable
-```
-
 Create a function:
 
 ```bash
@@ -196,10 +157,10 @@ functions:
 Run a build with:
 
 ```bash
-faas-cli pro build -f stack.yml
+faas-cli build -f stack.yml
 ```
 
-You'll also need an updated version of the node template to mount the secret passed in from the OpenFaaS Pro plugin. Update `template/node22/Dockerfile` and replace the second `npm i` command with:
+Update `template/node22/Dockerfile` and replace the second `npm i` command to mount the secret:
 
 ```Dockerfile
 RUN --mount=type=secret,id=npmrc,mode=0666,dst=/home/app/.npmrc npm i

docs/languages/php.md

@@ -72,7 +72,7 @@ That way you can pass in tokens for Composer, if necessary, GitHub tokens to get
 
 Bear in mind that any tokens used with `--build-arg` will be made available in the final container image.
 
-[OpenFaaS Standard's](https://openfaas.com/pricing) `faas-cli pro build` has a specific way to handle this without leaking secrets into the final image.
+Use [build secrets](/cli/build/#build-time-secrets) with `faas-cli build` to handle this without leaking secrets into the final image.
 
 ### PHP Extensions
 

docs/openfaas-pro/builder.md

@@ -133,7 +133,7 @@ Distribute the `key.pub` file to anyone who needs to build with secrets.
 
 #### Using build secrets with `faas-cli`
 
-Add `build_secrets` to your `stack.yaml`:
+Add `build_secrets` to your `stack.yaml`. The values must be file paths — `faas-cli` reads the file contents before sealing and sending them to the builder:
 
 ```yaml
 functions:
@@ -142,10 +142,13 @@ functions:
     handler: ./my-function
     image: registry.example.com/my-function:latest
     build_secrets:
-      pip_token: my-secret-token
-      registry_url: https://token:secret@registry.example.com/simple
+      pip_token: .secrets/pip_token.txt
+      registry_url: .secrets/registry_url.txt
 ```
 
+!!! warning "Do not store secrets in handler folders"
+    We recommend storing build secret files in a `.secrets/` folder alongside your `stack.yaml`. Never place secret files inside a function's handler folder — the handler contents are copied into the build context and will be included in the resulting container image, leaking your secrets.
+
 Use `--mount=type=secret` in your Dockerfile to access them:
 
 ```Dockerfile

docs/reference/yaml.md

@@ -152,6 +152,24 @@ functions:
 
 These can also be passed via the CLI using `faas-cli build --build-arg key=value` or `faas-cli up --build-arg key=value`
 
+### Function: Build Secrets (`build_secrets`)
+
+A map of build secrets can be used to mount sensitive values into the build process using Docker's `RUN --mount=type=secret` instruction. Unlike `build_args`, build secrets are not leaked into the final image.
+
+Each value is a file path. The `faas-cli` reads the file contents and passes them to Docker via `--secret id=<key>,src=<path>`.
+
+```yaml
+functions:
+  my-function:
+    handler: ./my-function
+    lang: python3-http
+    build_secrets:
+      pipconf: ${HOME}/.config/pip/pip.conf
+      netrc: ${HOME}/.netrc
+```
+
+See [Build-time secrets](/cli/build/#build-time-secrets) for detailed examples.
+
 ### Function: Environmental variables
 
 You can set configuration via environmental variables either in-line within the YAML file or in a separate external file. Do not store confidential or private data in environmental variables. See: secrets.