Add some quick notes on how to extend the API.

docs/extending-api.md

@@ -0,0 +1,34 @@
+# Extending the Cluster Operator API
+
+Cluster Operator aimed to expose everything you could set for an OpenShift cluster via a Kubernetes API.
+
+## Adding Fields to the API
+
+For an example commit, see [this PR](https://github.com/openshift/cluster-operator/commit/b29b162a108ea2273cabf59af7b52c3f40381c82#diff-57de84ac14e902638c6bcdbb05b813f3).
+
+ 1. Add your field to the [unversioned types.go](https://github.com/openshift/cluster-operator/blob/master/pkg/apis/clusteroperator/types.go) and the [versioned types.go](https://github.com/openshift/cluster-operator/blob/master/pkg/apis/clusteroperator/v1alpha1/types.go).
+   * These two files need to be kept basically in sync.
+   * Follow the existing API examples. Note the use of json tags to control serialization, "// +optional" fields, etc.
+   * If you would like defaulting for your field, see the defaults.go in each respective directory.
+   * If you would like validation on your field, see the pkg/apis/clusteroperator/validation. There are examples here as well as unit tests.
+ 1. Auto-generate code for modified type definition: `make build`
+   * You will see several autogenerated files get updated, client code, openapi, etc.
+ 1. Re-deploy Cluster Operator.
+   * Depends on how you are working but typically for developers using oc cluster up, this is:
+     * `$ ansible-playbook contrib/ansible/deploy-devel-playbook.yml -e fake_deployment=false -e push_images=true`
+ 1. Your API should now be ready, you can set the new field in your incoming ClusterDeployment yaml.
+
+## ClusterDeployment -> Cluster
+
+ClusterDeployments result in the creation of Clusters, an upstream type vendored in from the cluster-api project. You can see the definition of a cluster [here](https://github.com/openshift/cluster-operator/blob/master/vendor/sigs.k8s.io/cluster-api/pkg/apis/cluster/v1alpha1/cluster_types.go#L40). This generic Cluster type from upstream has a field for provider specific configuration, where we store our own data. You can see our AWS specific type [AWSClusterProviderConfig](https://github.com/openshift/cluster-operator/blob/master/pkg/apis/clusteroperator/v1alpha1/types.go#L202).
+
+Most of our controllers watch for Clusters, not ClusterDeployments. Depending on where you need to *use* your data, you may need to ensure it is transferred from ClusterDeployment, to the AWSClusterProviderConfig. This process happens in [clusterdeployment_controller.go](https://github.com/openshift/cluster-operator/blob/master/pkg/controller/clusterdeployment/clusterdeployment_controller.go#L620) and calls this [BuildCluster](https://github.com/openshift/cluster-operator/blob/master/pkg/controller/controller_utils.go#L526) function.
+
+## Using Your New Field
+
+In Cluster Operator code you should now be able to use your field.
+
+If your field is meant to translate to an openshift-ansible inventory option, see our [pkg/ansible/generate.go](https://github.com/openshift/cluster-operator/blob/master/pkg/ansible/generate.go) library. In here you will see most functions accept a AWSClusterSpec, which is a field on the AWSClusterProviderConfig we linked above. Here you could modify the Ansible templates according to the new fields you added to ClusterDeployment, and AWSClusterProviderConfig.
+
+
+