Proposed change

We may be able to remove the additional create Certificate step from SSL page.. https://docs.openfaas.com/reference/ssl/kubernetes-with-cert-manager/

Context

It seems like cert-manager's Ingress shim (available since 0.2.2) automatically creates certificates if an Ingress object is decorated appropriately. This is simpler than us instructing the user to create a separate Certificate object.

Found by: @ajaegle

openfaas/ingress-operator#6

Your Environment

We should test that the certificate is created automatically before removing the explicit step.

Proposed change

On page https://docs.openfaas.com/contributing/get-started/

Split out the list of repos into its own page and ToC entry.

Context

The page is too long and may be overwhelming to new people.

Also - please change the www repo to openfaas.github.io (its new name) - Done through c06df19

faas-cli supports --token flag since #faas-cli/pull/649 which is missing in the CLI docs

Currently searching for a way to add a link to contribute to documentation to each page. It makes it easier to contribute documentation. Worst case can Derek check for text verbatim in all files in a PR?

This should loosely model the templates used for the "faas" repo but have specific questions / prompts which relate to adding documentation.

Checkpoints may include:

• I have tested the markdown appearance with Docker
• I have tested any new instructions
• I am the author or have permission to share this text and reference the source

On https://docs.openfaas.com/deployment/kubernetes/#deploy-with-ssl the link Using nginx-ingress and cert-manager is a dead link because it points to https://docs.openfaas.com/reference/ssl/kubernetes-with-cert-manager.md

Proposed change

Update the link Using nginx-ingress and cert-manager to point to https://docs.openfaas.com/reference/ssl/kubernetes-with-cert-manager/

Context

This was reported as a dead link in Slack

The gateway currently exposes prometheus metrics that users may be interested in. We should document these metrics and perhaps some of the common queries they would want to use.

Proposed change

faas-cli logs needs to be documented

Context

This feature is being added by @LucasRoesler and it provides server-side logs from the kubelet or Docker Swarm.

Find a place in the CLI docs to document how the --tag flag works.

Remember this covers build/push and deploy - do we really want to duplicate the text in each part - or could it be a sub-page of the CLI heading?

openfaas/faas-cli#465

Here it is suggested that the user should deploy the stack and then run in the sample functions using the CLI using faas deploy. It then explains that within a few seconds (or minutes depending upon connection speed) the user will be able to hit the UI.

Suggestion is that deploying sample functions should not be attempted until the UI is available as that indicates the gateway is available.

ref: faas-cli#421

On Issues with TLS the code blocks are incorrectly formatted. Just a few spaces need to be added to the backticks, as shown here.

This section:

https://github.com/openfaas/docs/blob/master/docs/deployment/kubernetes.md#link-the-image-pull-secret-to-a-namespace-service-account

Suggests the secret name to be used should be myPrivateRepo. This causes the following error:

The Secret "myPrivateRepo" is invalid: metadata.name: Invalid value: "myPrivateRepo": a DNS-1123 subdomain must consist of lower case alphanumeric characters, '-' or '.', and must start and end with an alphanumeric character (e.g. 'example.com', regex used for validation is 'a-z0-9?(.a-z0-9?)*')

Suggest we move to a hypenated all lower case value.

Proposed change

The Add TLS to openfaas script contains a nested ingress entry. The correct script template should be:

# tls.yml
ingress:
  enabled: true
  annotations:
    kubernetes.io/ingress.class: nginx
    certmanager.k8s.io/issuer: letsencrypt-staging
    certmanager.k8s.io/acme-challenge-type: http01
  tls:
    - hosts:
        - openfaas.mydomain.com
      secretName: openfaas-crt
  hosts:
    - host: openfaas.mydomain.com
      serviceName: gateway
      servicePort: 8080
      path: /

Context

Your Environment

• FaaS-CLI version ( Full output from: faas-cli version ):

• Docker version docker version (e.g. Docker 17.0.05 ):

• Are you using Docker Swarm or Kubernetes (FaaS-netes)?

• Operating System and version (e.g. Linux, Windows, MacOS):

• Link to your project or a code example to reproduce issue:

• Please also follow the troubleshooting guide and paste in any other diagnostic information you have:

The command listed says:

$ curl -d "Hello" http://127.0.0.1:8080/async-function/figlet "X-Callback-Url: http://<your-ip>:8888"

but this just causes:

$ curl -d "Hello" http://127.0.0.1:8081/async-function/figlet "X-Callback-Url: http://localhost:8888"
curl: (6) Could not resolve host: X-Callback-Url: http

It needs a -H for headers in curl, so it should say:

$ curl -d "Hello" http://127.0.0.1:8080/async-function/figlet -H "X-Callback-Url: http://<your-ip>:8888"

However, this still doesn't seem to actually work as intended, although the curl command works at least.

There was an issue with question for separating stdout/stderr. There is information how to do this in the workshop, but not in the docs.

There could be other things missing as well.
This needs going trough the workshop and checking if everything is available.

Proposed change

Update the code blocks that reference a file with formatting that adds a label to the code block for better clarity. Easier to see it's a file, and not a command/output

example

To accomplish this, we would add the following markdown to the file code blocks:

!!! example "secrets.yaml"
    ```yaml
    apiVersion: bitnami.com/v1alpha1
    kind: SealedSecret
    metadata:
      creationTimestamp: null
      name: alexellis-fn-secrets
      namespace: openfaas-fn
    spec:
      encryptedData:
        incoming-webhook-url: (redacted)
    ```

Note: The code block is also indented so that the outline will wrap the entire block

Context

Want to make it easier to know that a block of code is reference to a file, and not some terminal input or output.

Your Environment

• FaaS-CLI version ( Full output from: faas-cli version ):
  0.8.3

• Docker version docker version (e.g. Docker 17.0.05 ):
  18.06.3-ce

• Are you using Docker Swarm or Kubernetes (FaaS-netes)?
  Both 😄

• Operating System and version (e.g. Linux, Windows, MacOS):
  Ubuntu 18.10

• Link to your project or a code example to reproduce issue:
  Image included above

• Please also follow the troubleshooting guide and paste in any other diagnostic information you have:
  N/A

Proposed change

The docs should show developers how to change the public port of the gateway. In both swarm and k8s this is not very complicated. We should warn users about exposing it publically, but for developers testing OpenFaaS they might have port conflicts on their local systems.

The docs should identify use cases and which files would need to be modified.

Context

Several users have asked about this in Slack. Documenting this will simplify the developer experience.

• Operating System and version (e.g. Linux, Windows, MacOS):

• Link to your project or a code example to reproduce issue:

• Please also follow the troubleshooting guide and paste in any other diagnostic information you have:

Typo in docs/contributing/get-started.md at line 44. "representive" --> "representative"

Opening this PR so it shows what the PR which I will open will contain

Extend the CLI part of the docs to describe:

• The constants which we use to set custom stores (template, function)

• Add explanation what the template store command is and how to use it

Proposed change

Update the cert-manager install instructions to match the last instructions from the cert-manager project.

Context

The current installation breaks with the following error message

helm install  --name cert-manager  --namespace kube-system  stable/cert-manager 
failed the first time with the following error: 
validation failed: [unable to recognize "": no matches for kind "Certificate" in vers ....

because there were breaking changes from version 0.5 to 0.6 and to 0.7. This was reported in slack and the upstream issue is here cert-manager/cert-manager#1255 Per the ticket in cert-manager , the current instructions can be used, but you must pin the cert-manger version to 0.5.2

Proposed change

The letsencrypt documentation at docs/docs/reference/ssl/kubernetes-with-cert-manager.md has the API version of acme set at 01. This needs to be updated to 02 for futureproofing.

Context

When you run kubectl -n openfaas describe issuer/letsencrypt-prod you receive the following message:

Status:
  Conditions:
    Last Transition Time:  2019-01-17T13:17:20Z
    Message:               Your ACME server URL is set to a v1 endpoint (https://acme-v01.api.letsencrypt.org/directory). You should update the spec.acme.server field to "https://acme-v02.api.letsencrypt.org/directory"
    Reason:                InvalidConfig
    Status:                False
    Type:                  Ready

Your Environment

• FaaS-CLI version ( Full output from: faas-cli version ): 0.8.3

• Docker version docker version (e.g. Docker 17.0.05 ): unsure - GKE version v1.11.5-gke.5

• Are you using Docker Swarm or Kubernetes (FaaS-netes)? Kubernetes on Google Cloud

• Operating System and version (e.g. Linux, Windows, MacOS): Linux

Proposed change

Currently in the docs for SSL on kubernetes there is an example code block for a letsencrypt issuer that is specified as an Issuer type. These are confined within a specific namespace where a ClusterIssuer would be global. This is then contradicted by the certificate entry that tries to bind to a ClusterIssuer of the same name, which fails.

Specifically the types Issuer from the letsencrypt-issuer.yaml code block:

# letsencrypt-issuer.yaml
apiVersion: certmanager.k8s.io/v1alpha1
kind: Issuer
metadata:
  name: letsencrypt-prod
  namespace: openfaas
spec:
  acme:
    # Email address used for ACME registration
    email: <your-email-here>
    http01: {}
    # Name of a secret used to store the ACME account private key
    privateKeySecretRef:
      key: ""
      name: letsencrypt-prod
    server: https://acme-v01.api.letsencrypt.org/directory
---
apiVersion: certmanager.k8s.io/v1alpha1
kind: Issuer
metadata:
  name: letsencrypt-staging
  namespace: openfaas
spec:
  acme:
    server: https://acme-staging.api.letsencrypt.org/directory
    # Email address used for ACME registration
    email: <your-email-here>
    # Name of a secret used to store the ACME account private key
    privateKeySecretRef:
      name: letsencrypt-staging
    http01: {}

Conflicts with the use of ClusterIssuer in openfaas-crt.yaml:

# openfaas-crt.yaml
apiVersion: certmanager.k8s.io/v1alpha1
kind: Certificate
metadata:
  name: openfaas-crt
spec:
  secretName: openfaas-crt
  dnsNames:
    - openfaas.mydomain.com
  acme:
    config:
      - http01:
          ingressClass: nginx
        domains:
          - openfaas.mydomain.com
  issuerRef:
    name: letsencrypt-staging
    kind: ClusterIssuer

Context

The certificate generation failed because the openfaas-crt object references a non-existant letsencrypt-prod, or letsencrypt-staging, ClusterIssuer because we created those names as Issuer.

We need to choose to either set all these references as Issuer and ensure the objects are all in the same namespace or set the references to ClusterIssuer.

Your Environment

• FaaS-CLI version ( Full output from: faas-cli version ): 0.8.3

• Docker version docker version (e.g. Docker 17.0.05 ): unsure - GKE version v1.11.5-gke.5

• Are you using Docker Swarm or Kubernetes (FaaS-netes)? Kubernetes on Google Cloud

• Operating System and version (e.g. Linux, Windows, MacOS): Linux

The indentation for Golang is not showing up.

Needs testing locally with instructions on this README file before pushing a change.

This still needs to be done, opening so I don't lose track of it.

We want to include the most interesting repositories from OpenFaas Incubator in Get started as a table with link and short description (like currently OpenFaas).

At the beginning I suggest to put there: of-watchdog and faas-idler but feel free to add another suggestions! :-)

Proposed change

Update to cert-manager 0.8.0

Full end to end testing will be required.

Be careful to see all the upgrade notes: https://docs.cert-manager.io/en/latest/tasks/upgrading/upgrading-0.7-0.8.html

Context

I had an email from LetsEncrypt saying that versions < 0.8.0 will be deprecated and blocked by LetsEncrypt from November.

Here is the web version: https://community.letsencrypt.org/t/blocking-old-cert-manager-versions/98753

Your Environment

Kubernetes

Links to /deployment/swarm/ instead of /deployment/docker-swarm/.

Proposed change

This would be an extension to the tutorial I wrote on HPA with CPU/memory, but showing how to use custom metrics instead. i.e. those exposed by the watchdog here

Context

With this, users will be able to scale on:

• RPS (default)
• HPAv2 with CPU/memory (docs added recently)
• HPAv2 with custom metrics exposed at the Pod/watchdog level

Your Environment

This will cover Kubernetes only.

Proposed change

List vcenter-connector project

Here -> https://docs.openfaas.com/contributing/get-started/#openfaas-incubator

https://github.com/openfaas-incubator/vcenter-connector

Use the repo title as the text in the table.

Context

Your Environment

• FaaS-CLI version ( Full output from: faas-cli version ):

• Docker version docker version (e.g. Docker 17.0.05 ):

• Are you using Docker Swarm or Kubernetes (FaaS-netes)?

• Operating System and version (e.g. Linux, Windows, MacOS):

• Link to your project or a code example to reproduce issue:

• Please also follow the troubleshooting guide and paste in any other diagnostic information you have:

Proposed change

On the getting started doc, write a complete worked example for cloning/forking and raising a PR with Go code. https://docs.openfaas.com/contributing/get-started/

Detail flow with example commands for one of the repos:

• Find issue
• Ask to work on it
• Fork repo
• Clone original repo
• Add new remote side
• Make a change
• Test it
• Sign-off commit
• Push to remote
• Raise PR
• Fill out template
• Reference PR on issue
• Tell us about it

Add a note on how to sign a commit / amend it if someone got this wrong.

Context

Suggested by @bartsmykla during review of How to Contribute presentation

Your Environment

• FaaS-CLI version ( Full output from: faas-cli version ):

• Docker version docker version (e.g. Docker 17.0.05 ):

• Are you using Docker Swarm or Kubernetes (FaaS-netes)?

• Operating System and version (e.g. Linux, Windows, MacOS):

• Link to your project or a code example to reproduce issue:

• Please also follow the troubleshooting guide and paste in any other diagnostic information you have:

Proposed change

Document faas-cli secrets feature

Put this under the CLI heading and cover all the new verbs: create/update/remove and list.

Context

We're adding the feature as proposed here: openfaas/faas#807 openfaas/faas-cli#577

Your Environment

• FaaS-CLI version ( Full output from: faas-cli version ):

This should say that it will be in a specific version of OpenFaaS and the CLI (0.9.14 for the GW) and for the CLI look at what the next release version will be and use that.

--sign and --key were introduced in openfaas/faas-cli#530.

These should be described, perhaps in an invoke section, under the CLI

Update https://docs.openfaas.com/cli/templates/ to add the new PHP7 template.

The new build docs page in #32 is very sparse, it should cover some of the advanced feature of the build command such as --filter and --parallel - these are essential for working with larger stacks.

Hi
I am finding that many of the links in the docs are 404, e.g. https://github.com/openfaas/faas/blob/master/guide/troubleshooting.md

Regarding to this issue, and talking with Alex, we could add documentation about how to deal with CORS when developing locally on SPAs (Single Page Applications).

• Explain CORS and why it may come up as a problem during local dev or production
• Explain about adding a proxy in front to make the caller think he's requesting the same domain
• Show a SPA app with Vue.js + webpack how to develop locally.

Proposed change

We should mention ARM deployment methods for Swarm and Kubernetes and the need to use -armhf templates. cc @tdicola of Adafruit

Context

Ref #105

I'll close the PR that was raised and we'll use this issue to track the two changes needed for new users. We should also highlight the two blog posts.

The button to copy from code blocks on the docs pages also copies the $ symbol.

Should the $ suffix be dropped now that the .md files are generating the docs site?
Does the docs generation process make it possible to strip the leading $?

The toubleshooting guide has grown quite large, nearly 500 lines now. That's not a bad thing, but I believe it should be re-organized to make it easier to navigate. It's also a bit difficult to see the different headings on the docs page. Difference between ## and ### are very slight.

Currently, the topics are focused on how to do something:

• Timeouts
• Healthcheck
• Watchdog

These are useful if you know what you're looking for, however, it's difficult to know what you need to do when something is wrong and you're not familiar with the project.

I propose the Troubleshooting guide be updated to a question/answer format to make it easier to find relevant information.

A good example of this is in the "Troubleshooting Swarm or Kubernetes" section: I forgot my gateway password

There have been a couple of conversations happening on Slack that have come up before. The members have linked to sections in the docs, but without knowing what to look for, the others have to ask.

Some examples of questions that came up (in the "openfaas" channel):

• Why doesn't auto-scaling work like I expect it?
• Why is my function not ready after faas-cli deploy?
• How do I invoke a function via cron job?
• How do I change the alert rules?
• I can't access the UI on localhost

Possibly some of these could go into a new "FAQ" page. Those questions that aren't really problems but more curiosity...

Proposed change

Update docs to use cert-manager 0.11.0 to keep up to date.

https://docs.cert-manager.io/en/release-0.11/

Context

This version has breaking changes in the annotations used and how issuers work.

Your Environment

Kubernetes 1.15 / 1.16

See how with Upgrading from v0.10 to v0.11

https://github.com/openfaas/docs/blob/master/docs/reference/secrets.md shows secrets being created with identifiers containing underscores. Should these be changed to hyphens to satisfy k8s DNS-1123 constraint?

$ kubectl version
Client Version: 
version.Info{
 Major:"1", 
 Minor:"10", 
 GitVersion:"v1.10.0", 
 GitCommit:"fc32d2f3698e36b93322a3465f63a14e9f0eaead", 
 GitTreeState:"clean", 
 BuildDate:"2018-03-26T16:55:54Z", 
 GoVersion:"go1.9.3", 
 Compiler:"gc", 
 Platform:"linux/amd64"
}

Server Version: 
version.Info{
 Major:"1", 
 Minor:"10", 
 GitVersion:"v1.10.0", 
 GitCommit:"fc32d2f3698e36b93322a3465f63a14e9f0eaead", 
 GitTreeState:"clean", 
 BuildDate:"2018-03-26T16:44:10Z", 
 GoVersion:"go1.9.3", 
 Compiler:"gc", 
 Platform:"linux/amd64"
 }

Using the command show on the docs page:

$ kubectl create secret generic secret_api_key --from-file=secret_api_key=/tmp/test

The Secret "secret_api_key" is invalid: metadata.name: Invalid value: "secret_api_key": 
a DNS-1123 subdomain must consist of lower case alphanumeric characters, '-' or '.', 
and must start and end with an alphanumeric character (e.g. 'example.com', 
regex used for validation is '[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*')

Proposed change

We should discuss and hint at how to support opentracing or tracing in general for functions. This is not about tracing the internals of OpenFaaS but supporting developers to add tracing to their functions.

Context

This has been asked about several times in Slack and also here openfaas/faas-netes#272

Production deployments of OpenFaaS should use an HA and Durable NATS installation to provide better stability. We should document how to install OpenFaaS and supporting an HA NATS cluster.

We have an SSL page for Kubernetes now but we should create one for Swarm - the simplest method I've used so far is Traefik which also provisions certificates using LetsEncrypt.

This is my example which I'm happy to donate to the documentation site: https://gist.github.com/alexellis/aad27285c099ed0878373569c0cdd567

I think it's also important to show how to enable basic auth for an embedded registry as part of this guide as that is a common ask and use-case for an OpenFaaS cluster. This is also included but we need to be careful re: the instructions for generating the Traefik basic auth password - since it is not straightforward and involves some manual steps (Google for this and you'll see it on StackOverflow) - the key thing is these instructions must be tested.

As mentioned here, the logos aren't aligned well when viewed on mobile.

Perhaps it would look better if we center align it.

All the valid options for the yaml stack format should be documented here.

Look to the CLI readme file for the basis of this information filling in any gaps around constraints and limits etc.

Keep this succinct but accurate then remove the content from the CLI readme.

Annotations act just like labels, but allow a broader range of values in the value field when using Kubernetes. Kubernetes also uses annotations for other purposes.

Users are not aware that the feature is available - openfaas/faas#803

@ewilde please could you document this new flag in the YAML reference section?

Thanks

Currently the YAML section at https://docs.openfaas.com/reference/yaml/ is fairly complete, however it misses some of the more recent features:

• build_options
• readonly_root_filesystem
• skip_build

Proposed change

Add ToC page on Service mesh

Context

Include direct links to the work of @stefanprodan and @matipan

https://github.com/stefanprodan/istio-gke

https://github.com/openfaas-incubator/openfaas-linkerd2

Your Environment

• FaaS-CLI version ( Full output from: faas-cli version ):

• Docker version docker version (e.g. Docker 17.0.05 ):

• Are you using Docker Swarm or Kubernetes (FaaS-netes)?

• Operating System and version (e.g. Linux, Windows, MacOS):

• Link to your project or a code example to reproduce issue:

• Please also follow the troubleshooting guide and paste in any other diagnostic information you have:

It could help to avoid 404 errors

Relate-to: #177