tigera/docs

Unified docs repository for Calico and Tigera

Calico & Tigera Docs

This is the full set of product docs for Calico & Tigera. It includes our Open Source (Project Calico) docs as well as our Enterprise and Cloud docs.

This website is built using Docusaurus 2, a modern static website generator.

Prerequisites

Either

• docker (to run the containerised version of the build)

Or

• Node.js v18.18.2+ (v18.18.2 recommended). Use the outstanding nvm tool to manage your node versions.
• yarn npm install -g yarn
• Fork and clone our docs repo https://github.com/tigera/docs

Local development

make start 

or

make start CONTAINERIZED=true

This command starts a local development server on http://localhost:3000. Most changes are reflected live without having to restart the server. This build is faster, but does not produce all the warnings and errors of a full build.

Full build and serve

make build
make serve

or

make build CONTAINERIZED=true
make serve CONTAINERIZED=true

This command generates static content into the build directory and can be served using any static content hosting service. This is a full build which is exactly what Netlify runs to build the site, therefore, you will get more warning and error output. If you are trying to reproduce an error on Netlify, this is a great place to start.

Building the site with unreleased docs versions

In production, we don't build or publish unreleased doc sets. If you'd like to preview changes to those versions locally, you can run the following commands:

make serve-next

make build-next
make serve

Viewing changes in preview builds

Each pull request against the main branch generates two preview builds. You can find links to these preview builds as comments from Netlify.

• Deploy preview. A full build with our production configuration.
• Deploy preview for calico-docs-preview-next. This builds the site based on the current state of our unversioned development directories:
  • calico/
  • calico-enteprise/
  • calico-cloud/

If you're making changes to an upcoming version of any of the products, review your changes in calico-docs-preview-next.

Viewing your changes locally for unreleased documentation

If you prefer to view changes to unreleased documentation locally, you must modify the docusuarus.config.js file. Add 'next' to the list for onlyIncludeVersions for the product docs you want to build.

      {
        id: 'calico',
        path: 'calico',
        routeBasePath: 'calico',
        editCurrentVersion: true,
        onlyIncludeVersions: ['next','3.27','3.26','3.25'], // 'next' is added to build the in-development docs  
        versions: {
          current: {
            label: 'Next',
            path: 'next',
            banner: 'unreleased',
          },
          3.28: {
            label: '3.28 (latest)',
            path: '3.28',
            banner: 'none'
          },
          3.27: {
            label: '3.27 (latest)',
            path: 'latest',
            banner: 'none',
          },

With this configuration, run yarn start or yarn build && yarn serve to see your changes.

Updating the Operator API docs

This repo includes functionality to automatically update the Operator API docs from the current version of Operator for each branch. The following Makefile targets will help you update the docs you want to update:

Automatically update all branches for all products:

make autogen

Automatically update all branches for a specific product:

make autogen_calico         # To update all Calico OSS releases
make autogen_enterprise     # To update all Calico Enterprise releases
make autogen_cloud          # To update all Calico Cloud releases

Detect and print a list of all of the makefile targets for each branch for all products. You can then run one of these targets to update the operator reference specifically for that branch.

# Get the list of operator reference update targets
❯ make show_current_branches
Calico branch targets:
* calico__operator_reference
* calico_versioned_docs/version-3.25__operator_reference
* calico_versioned_docs/version-3.26__operator_reference
* calico_versioned_docs/version-3.27__operator_reference

Calico enterprise branch targets:
* calico-enterprise__operator_reference
* calico-enterprise_versioned_docs/version-3.16__operator_reference
* calico-enterprise_versioned_docs/version-3.17__operator_reference
* calico-enterprise_versioned_docs/version-3.18__operator_reference
* calico-enterprise_versioned_docs/version-3.18-2__operator_reference
* calico-enterprise_versioned_docs/version-3.19-1__operator_reference

Calico cloud branch targets:
* calico-cloud__operator_reference
* calico-cloud_versioned_docs/version-19-1__operator_reference

# Trigger the operator reference update for Calico Enterprise v3.18
❯ make calico-enterprise_versioned_docs/version-3.18__operator_reference
...build output here...

docs's Issues

How-to guide for setting memory and CPU limits, requests.

Based on this issue: projectcalico/calico#7561

We have reference documentation for this, but it's hard to follow if you don't know what you're looking for.

A "How-To" style doc would be really useful for a lot of users - we get this question a lot! It can cover all of the different pods / containers that support this.

CC @bmckercher123

Service Advertisement BGP, update to recent Metallb configuration

Hello. In the documentation regarding load balancer service advertisement with BGP, it mentions to use Metallb to assign the IPs. However, it uses the old configuration method with the ConfigMap instead of the more recent CRDs (metallb v0.13):

kubectl create -f - <<EOF
apiVersion: v1
kind: ConfigMap
metadata:
  namespace: metallb-system
  name: config
data:
  config: |
    address-pools:
    - name: default
      protocol: bgp
      addresses:
      - x.x.x.x/16
EOF

It might be more interesting to propose the newer Metallb configuration:

kubectl create -f - <<EOF
kind: IPAddressPool
metadata:
  name: default
  namespace: metallb-system
spec:
  addresses:
  - x.x.x.x/16
EOF

There might be a reason that I'm not aware of to keep this as it is. Anyways, thank you!

Need to correct the Installation example

Here calico_versioned_docs/version-3.26/operations/image-options/alternate-registry.mdx
at the end we have an example of Installation.
registry field should be spec.registry but in the example it is spec.imagePullSecrets[0].registry

Project calico documentation: Expand calico network policy log documentation

As a Kubernetes beginner, I started to secure the K8s Cluster with Calico Network Policyies and also wanted to log a few of them. I had to struggle with some problems there at the beginning, because I didn't understand how logging works at calico. Therefore I had looked for help in Slack (and got it successfully) :)

To make it easier for more beginners I made some notes and thought about what could be added in the documentation.

1. I figured out (maybe a bug) that if you want to allow/deny and log something, the "Log" action have to be always before the allow/deny action in the order . When not, nothing will be logged, because that creates two iptables rules. I would name this on the documentation

2. It would have been a great help to me if the logging of Calico's network policies had been better described . Before I had an conversation with Lance from calico, I didn´t know anything about that. I would explain that calico "only" adds some parameter to the iptables rule like the logging and prefix parameter. Also that the responsibility of calico ends (at least currently) there. Maybe also the standard syslog path like /var/log/messages or /var/log/syslog. I was only looking before at /var/log/calico/...

3. Best Practise Network Policy Logging: e.g. Global Deny, that logs each connection attempt, which will be dropped

4. Example Calico Network Policy Log

Fail to install calico on Windows using the operator

Following the guide to create a Kubernetes Cluster with Windows Nodes using Install using Operator ends up with pod/calico-node-windows not spawning due to encapsulation being set by default on VXLANCrossSubnet, which is not supported.

The missing step from the guide is the part presented in the manual installation guide on If using Calico VXLAN networking

/cc @coutinhop

Failed to Upgrade Calico v3.25.1 to v3.26.0

I upgraded from calico v3.25.1 to calico v3.26.0 as described in "Upgrading an installation that uses manifests and the Kubernetes API datastore" but it failed. calico-node's status becomes Init:CrashLoopBackOff.

calico-cni-plugin is not created when execute kubectl replace. (calico-cni-plugin was added in v3.26.0 projectcalico/calico#7106 )so I think we need to change kubectl replace to kubectl apply.https://github.com/tigera/docs/blob/main/calico/operations/upgrading/kubernetes-upgrade.mdx?plain=1#L136

# kubectl version
WARNING: This version information is deprecated and will be replaced with the output from kubectl version --short.  Use --output=yaml|json to get the full version.
Client Version: version.Info{Major:"1", Minor:"27", GitVersion:"v1.27.2", GitCommit:"7f6f68fdabc4df88cfea2dcf9a19b2b830f1e647", GitTreeState:"clean", BuildDate:"2023-05-17T14:20:07Z", GoVersion:"go1.20.4", Compiler:"gc", Platform:"linux/amd64"}
Kustomize Version: v5.0.1
Server Version: version.Info{Major:"1", Minor:"27", GitVersion:"v1.27.2", GitCommit:"7f6f68fdabc4df88cfea2dcf9a19b2b830f1e647", GitTreeState:"clean", BuildDate:"2023-05-17T14:13:28Z", GoVersion:"go1.20.4", Compiler:"gc", Platform:"linux/amd64"}

# calicoctl version
Client Version:    v3.25.1
Git commit:        82dadbce1
Cluster Version:   v3.25.1
Cluster Type:      k8s,bgp,kubeadm,kdd

# kubectl replace -f 3.26.0/calico.yaml
poddisruptionbudget.policy/calico-kube-controllers replaced
serviceaccount/calico-kube-controllers replaced
serviceaccount/calico-node replaced
configmap/calico-config replaced
customresourcedefinition.apiextensions.k8s.io/bgpconfigurations.crd.projectcalico.org replaced
customresourcedefinition.apiextensions.k8s.io/bgppeers.crd.projectcalico.org replaced
customresourcedefinition.apiextensions.k8s.io/blockaffinities.crd.projectcalico.org replaced
customresourcedefinition.apiextensions.k8s.io/caliconodestatuses.crd.projectcalico.org replaced
customresourcedefinition.apiextensions.k8s.io/clusterinformations.crd.projectcalico.org replaced
customresourcedefinition.apiextensions.k8s.io/felixconfigurations.crd.projectcalico.org replaced
customresourcedefinition.apiextensions.k8s.io/globalnetworkpolicies.crd.projectcalico.org replaced
customresourcedefinition.apiextensions.k8s.io/globalnetworksets.crd.projectcalico.org replaced
customresourcedefinition.apiextensions.k8s.io/hostendpoints.crd.projectcalico.org replaced
customresourcedefinition.apiextensions.k8s.io/ipamblocks.crd.projectcalico.org replaced
customresourcedefinition.apiextensions.k8s.io/ipamconfigs.crd.projectcalico.org replaced
customresourcedefinition.apiextensions.k8s.io/ipamhandles.crd.projectcalico.org replaced
customresourcedefinition.apiextensions.k8s.io/ippools.crd.projectcalico.org replaced
customresourcedefinition.apiextensions.k8s.io/ipreservations.crd.projectcalico.org replaced
customresourcedefinition.apiextensions.k8s.io/kubecontrollersconfigurations.crd.projectcalico.org replaced
customresourcedefinition.apiextensions.k8s.io/networkpolicies.crd.projectcalico.org replaced
customresourcedefinition.apiextensions.k8s.io/networksets.crd.projectcalico.org replaced
clusterrole.rbac.authorization.k8s.io/calico-kube-controllers replaced
clusterrole.rbac.authorization.k8s.io/calico-node replaced
clusterrole.rbac.authorization.k8s.io/calico-cni-plugin replaced
clusterrolebinding.rbac.authorization.k8s.io/calico-kube-controllers replaced
clusterrolebinding.rbac.authorization.k8s.io/calico-node replaced
clusterrolebinding.rbac.authorization.k8s.io/calico-cni-plugin replaced
daemonset.apps/calico-node replaced
deployment.apps/calico-kube-controllers replaced
Error from server (NotFound): error when replacing "3.26.0/calico.yaml": serviceaccounts "calico-cni-plugin" not found
Error from server (NotFound): error when replacing "3.26.0/calico.yaml": customresourcedefinitions.apiextensions.k8s.io "bgpfilters.crd.projectcalico.org" not found


# kubectl get pods -n kube-system
NAME                                       READY   STATUS                  RESTARTS      AGE
calico-kube-controllers-786b679988-d9qdv   0/1     Running                 1 (7s ago)    73s
calico-node-l42zf                          0/1     Init:CrashLoopBackOff   3 (21s ago)   75s
calico-node-tjkh5                          0/1     Init:CrashLoopBackOff   2 (20s ago)   45s
coredns-5d78c9869d-l6rd2                   1/1     Running                 0             6m16s
coredns-5d78c9869d-v5jd7                   1/1     Running                 0             6m16s
etcd-k8s-master                            1/1     Running                 16            6m29s
kube-apiserver-k8s-master                  1/1     Running                 16            6m29s
kube-controller-manager-k8s-master         1/1     Running                 12            6m29s
kube-proxy-kl5gx                           1/1     Running                 0             5m43s
kube-proxy-tvxkh                           1/1     Running                 0             6m16s
kube-scheduler-k8s-master                  1/1     Running                 17            6m29s


# kubectl logs -n kube-system calico-node-l42zf -c install-cni
2023-06-07 09:45:50.047 [INFO][1] cni-installer/<nil> <nil>: Running as a Kubernetes pod
2023-06-07 09:45:50.213 [INFO][1] cni-installer/<nil> <nil>: File is already up to date, skipping file="/host/opt/cni/bin/bandwidth"
2023-06-07 09:45:50.213 [INFO][1] cni-installer/<nil> <nil>: Installed /host/opt/cni/bin/bandwidth
2023-06-07 09:45:50.297 [INFO][1] cni-installer/<nil> <nil>: File is already up to date, skipping file="/host/opt/cni/bin/calico"
2023-06-07 09:45:50.297 [INFO][1] cni-installer/<nil> <nil>: Installed /host/opt/cni/bin/calico
2023-06-07 09:45:50.366 [INFO][1] cni-installer/<nil> <nil>: File is already up to date, skipping file="/host/opt/cni/bin/calico-ipam"
2023-06-07 09:45:50.366 [INFO][1] cni-installer/<nil> <nil>: Installed /host/opt/cni/bin/calico-ipam
2023-06-07 09:45:50.368 [INFO][1] cni-installer/<nil> <nil>: File is already up to date, skipping file="/host/opt/cni/bin/flannel"
2023-06-07 09:45:50.368 [INFO][1] cni-installer/<nil> <nil>: Installed /host/opt/cni/bin/flannel
2023-06-07 09:45:50.372 [INFO][1] cni-installer/<nil> <nil>: File is already up to date, skipping file="/host/opt/cni/bin/host-local"
2023-06-07 09:45:50.372 [INFO][1] cni-installer/<nil> <nil>: Installed /host/opt/cni/bin/host-local
2023-06-07 09:45:50.434 [INFO][1] cni-installer/<nil> <nil>: File is already up to date, skipping file="/host/opt/cni/bin/install"
2023-06-07 09:45:50.434 [INFO][1] cni-installer/<nil> <nil>: Installed /host/opt/cni/bin/install
2023-06-07 09:45:50.437 [INFO][1] cni-installer/<nil> <nil>: File is already up to date, skipping file="/host/opt/cni/bin/loopback"
2023-06-07 09:45:50.437 [INFO][1] cni-installer/<nil> <nil>: Installed /host/opt/cni/bin/loopback
2023-06-07 09:45:50.441 [INFO][1] cni-installer/<nil> <nil>: File is already up to date, skipping file="/host/opt/cni/bin/portmap"
2023-06-07 09:45:50.441 [INFO][1] cni-installer/<nil> <nil>: Installed /host/opt/cni/bin/portmap
2023-06-07 09:45:50.444 [INFO][1] cni-installer/<nil> <nil>: File is already up to date, skipping file="/host/opt/cni/bin/tuning"
2023-06-07 09:45:50.444 [INFO][1] cni-installer/<nil> <nil>: Installed /host/opt/cni/bin/tuning
2023-06-07 09:45:50.444 [INFO][1] cni-installer/<nil> <nil>: Wrote Calico CNI binaries to /host/opt/cni/bin

2023-06-07 09:45:50.461 [INFO][1] cni-installer/<nil> <nil>: CNI plugin version: v3.26.0

2023-06-07 09:45:50.461 [INFO][1] cni-installer/<nil> <nil>: /host/secondary-bin-dir is not writeable, skipping
W0607 09:45:50.461386       1 client_config.go:618] Neither --kubeconfig nor --master was specified.  Using the inClusterConfig.  This might not work.
2023-06-07 09:45:50.874 [ERROR][1] cni-installer/<nil> <nil>: Unable to create token for CNI kubeconfig error=serviceaccounts "calico-cni-plugin" not found
2023-06-07 09:45:50.874 [FATAL][1] cni-installer/<nil> <nil>: Unable to create token for CNI kubeconfig error=serviceaccounts "calico-cni-plugin" not found

Helm installation docs have some error

https://docs.tigera.io/calico-enterprise/3.15/getting-started/install-on-clusters/kubernetes/helm

helm install calico-enterprise tigera-operator-v3.15.5-0.tgz \ --set-file imagePullSecrets.tigera-pull-secret=<path/to/pull/secret>,tigera-prometheus-operator.imagePullSecrets.tigera-pull-secret=<path/to/pull/secret> \ --namespace tigera-operator

There is no chart called calico-enterprise in the archive but only tigera-operator, the overall instruction seems to not working if you don't have already installed calico CRDs

Spelling

There are a number of errors that cspell doesn't catch that could be fixed...

including...

adminstrators
associat
calicocttl
contrack
docusuarus
eccess
Entreprise
explicitely
feild
gress
hotpots
Kuberentes
loadblalancer
maintenace
neiljerram
outlyers
overriden
parner
runnibng
selctors
seperately
Syle
updting
verison

https://github.com/jsoref/tigera-docs/actions/runs/6887181623#summary-18733976011

Grammar: regardless

regardless if you doesn't work grammatically, it should be regardless of whether you

[Feature] add a supplement to the Calico for Windows, Install using Operator

[background]

I am building a Windows-supported Kubernetes cluster with OCI.
OKE, OCI's managed Kubernetes, does not support Windows, so the Cluster API is used to build the cluster.
I thought it would be nice to have a supplement there, so I'd like to include it in the documentation if you don't mind.

[ex]

• I want to post a link to the CRD for Installation. The example creates a minimally configured installation, but understanding more parameters in advance will make it easier to build.
  • https://docs.tigera.io/calico/latest/reference/installation/api
• I want to add a note that calico-node-windows crashed because it could not build a virtual network when the VXLAN Adapter is not described in the Installation CRD.

I would like to create a PR once I get your review.

Calico Helm Upgrade from v3.23.0 Missing CRD Update Step

Instructions to update Helm deployed Calico on a Kubernetes cluster is missing a step to update the CRDs if you are upgrading from a version prior to v3.23.0

Following the instructions looks like it passes (no pod errors if you just run a kubectl get pod -n calico-system but looking at the logs for the tigera-operator will reveal many resource update errors. This is because the CRDs have not been updated.

This was partially fixed in the "All other upgrades" section with #637 but the CRD update needs to happen with ALL updates.

PR to resolve incoming.