Documentation and manifest mismatch

[aceeric]

This page: https://projectcalico.docs.tigera.io/getting-started/kubernetes/self-managed-onprem/onpremises

Provides direction to download https://raw.githubusercontent.com/projectcalico/calico/v3.24.1/manifests/tigera-operator.yaml - which contains CRD defs. Those CRDs are all:

  versions:
  - name: v1

So:

$ kubectl api-resources  | grep 'NAME\|calico'
NAME                              SHORTNAMES   APIVERSION                             NAMESPACED   KIND
...
ippools                                        crd.projectcalico.org/v1               false        IPPool
...

I was trying to install Tigera/Calico and ran into a problem. So after the tigera download/install I thought I would try: https://projectcalico.docs.tigera.io/getting-started/kubernetes/hardway/configure-ip-pools.

That page says:

cat > pool1.yaml <<EOF
apiVersion: projectcalico.org/v3
kind: IPPool
metadata:
  name: pool1
spec:
  cidr: 192.168.0.0/18
  ipipMode: Never
  natOutgoing: true
  disabled: false
  nodeSelector: all()
EOF

Notice API version mismatch. Neither documentation page is versioned so it's natural to think that they're talking about the same version/release. In other words its natural to assume that the CRD versions in the Tigera scenario are the same version as the hard way scenario but that seems not to be the case. Is this intentional?

Thank you.

[Josh-Tigera]

The difference is subtle but crd.projectcalico.org/v1 != projectcalico.org/v3 and is intentional. The latter is a kind of placeholder to reference an older APIVersion that we no longer use, so internally we translate them to the former "real" version associated with the CRD (ie. crd.projectcalico.org/v1). Very understandable how this is confusing though given how one string is what looks like a subset of the other.

[caseydavenport]

For more info: #6412