adding-an-api.md

How to add an API to Calico

Calico uses Kubernetes style APIs. To add a new API to Calico, or to add a new field to an existing API, use the following steps.

Adding a new API field

For most cases, a new API field on an existing API is all that is needed. To add a new API field:

1. Update the structures in the v3 API

2. Run make generate to update generated code and CRDs.

3. Add the new logic for your field, including validation.

4. Add unit tests for your field.

Designing a new Calico API

1. Start by opening a GitHub issue or design document to design the feature. Consider the following:

   • What component(s) need to know about this resource?
   • What is the correct abstraction for this feature?
   • Is there an existing API that makes sense for this feature instead?

2. Agree on a design for the new API. Read and follow the Kubernetes API conventions for new APIs.

3. Get your proposed API reviewed.

Coding a new Calico API

1. Add the new structure to the api/pkg/apis/projectcalico/v3 in its own go file.

   • Include kubebuilder validation and defaulting where appropriate.

2. Run code and CRD generation - make generate

3. Add client code to libcalico-go for the new API, using existing resources as a template.

   • https://github.com/projectcalico/calico/tree/master/libcalico-go/lib/clientv3
   • https://github.com/projectcalico/calico/blob/master/libcalico-go/lib/backend/k8s/k8s.go

4. Add unit tests for the API, using existing ones as a template.

5. Add CRUD commands and tests to calicoctl using existing ones as a template.

6. If felix or confd needs the new resource, add it to either the felixsyncer or bgpsyncer respectively.