Merge pull request #68361 from liztio/godoc-kubeadm-v1alpha3

Automatic merge from submit-queue. If you want to cherry-pick this change to another branch, please follow the instructions here: https://github.com/kubernetes/community/blob/master/contributors/devel/cherry-picks.md.

Add a completely populated yaml InitConfig to the v1lapha3 dodoc

**What this PR does / why we need it**:
The existing docs are located in [k/website][website], which means it's difficult to keep them up to date. Having an example next to the code will make it much easier to update the docs in lockstep with spec changes.

**Which issue(s) this PR fixes** *(optional, in `fixes #<issue number>(, fixes #<issue_number>, ...)` format, will close the issue(s) when PR gets merged)*:
Fixes kubernetes/kubeadm#1085

**Special notes for your reviewer**:

**Release note**:

```release-note
NONE
```

cmd/kubeadm/app/apis/kubeadm/v1alpha3/bootstraptokenstring.go

@@ -14,10 +14,6 @@ See the License for the specific language governing permissions and
 limitations under the License.
 */
 
-// Package v1alpha2 holds the external kubeadm API types of version v1alpha2
-// Note: This file should be kept in sync with the similar one for the internal API
-// TODO: The BootstrapTokenString object should move out to either k8s.io/client-go or k8s.io/api in the future
-// (probably as part of Bootstrap Tokens going GA). It should not be staged under the kubeadm API as it is now.
 package v1alpha3
 
 import (

cmd/kubeadm/app/apis/kubeadm/v1alpha3/doc.go

@@ -14,7 +14,83 @@ See the License for the specific language governing permissions and
 limitations under the License.
 */
 
-// Package v1alpha2 is the package that contains the libraries that drive the kubeadm binary.
+// Package v1alpha3 is the API (config file) for driving the kubeadm binary.
+// Some of these options are also available as command line flags, but
+// the preferred way to configure kubeadm is to pass a YAML file in with the
+// --config option.
+//
+// A fully populated example of the schema:
+//	apiVersion: kubeadm.k8s.io/v1alpha3
+//	kind: InitConfiguration
+//	etcd:
+//	  # one of local or external
+//	  local:
+//	    image: "k8s.gcr.io/etcd-amd64:3.2.18"
+//	    dataDir: "/var/lib/etcd"
+//	    extraArgs:
+//	      listen-client-urls: "http://10.100.0.1:2379"
+//	    serverCertSANs:
+//	    -  "ec2-10-100-0-1.compute-1.amazonaws.com"
+//	    peerCertSANs:
+//	    - "10.100.0.1"
+//	  external:
+//	    endpoints:
+//	    - "10.100.0.1:2379"
+//	    - "10.100.0.2:2379"
+//	    caFile: "/etcd/kubernetes/pki/etcd/etcd-ca.crt"
+//	    certFile: "/etcd/kubernetes/pki/etcd/etcd.crt"
+//	    certKey: "/etcd/kubernetes/pki/etcd/etcd.key"
+//	networking:
+//	  serviceSubnet: "10.96.0.0/12"
+//	  podSubnet: "10.100.0.1/24"
+//	  dnsDomain: "cluster.local"
+//	kubernetesVersion: "v1.12.0"
+//	ControlPlaneEndpoint: "10.100.0.1:6443"
+//	apiServerExtraArgs:
+//	  authorization-mode: "Node,RBAC"
+//	controlManagerExtraArgs:
+//	  node-cidr-mask-size: 20
+//	schedulerExtraArgs:
+//	  address: "10.100.0.1"
+//	apiServerCertSANs:
+//	- "10.100.1.1"
+//	- "ec2-10-100-0-1.compute-1.amazonaws.com"
+//	certificateDirectory: "/etc/kubernetes/pki"
+//	imageRepository: "k8s.gcr.io"
+//	unifiedControlPlaneImage: "k8s.gcr.io/controlplane:v1.12.0"
+//	auditPolicyConfiguration:
+//	  # https://kubernetes.io/docs/tasks/debug-application-cluster/audit/#audit-policy
+//	  path: "/var/log/audit/audit.json"
+//	  logDir: "/var/log/audit"
+//	  logMaxAge: 7 # in days
+//	featureGates:
+//	  selfhosting: false
+//	clusterName: "example-cluster"
+//	bootstrapTokens:
+//	- token: "9a08jv.c0izixklcxtmnze7"
+//	  description: "kubeadm bootstrap token"
+//	  ttl: "24h"
+//	  usages:
+//	  - "authentication"
+//	  - "signing"
+//	  groups:
+//	  - "system:bootstrappers:kubeadm:default-node-token"
+//	nodeRegistration:
+//	  name: "ec2-10-100-0-1"
+//	  criSocket: "/var/run/dockershim.sock"
+//	  taints:
+//	  - key: "kubeadmNode"
+//	    value: "master"
+//	    effect: "NoSchedule"
+//	  kubeletExtraArgs:
+//	    cgroupDriver: "cgroupfs"
+//	apiEndpoint:
+//	  advertiseAddress: "10.100.0.1"
+//	  bindPort: 6443
+//
+// TODO: The BootstrapTokenString object should move out to either k8s.io/client-go or k8s.io/api in the future
+// (probably as part of Bootstrap Tokens going GA). It should not be staged under the kubeadm API as it is now.
+//
 // +k8s:defaulter-gen=TypeMeta
 // +groupName=kubeadm.k8s.io
 // +k8s:deepcopy-gen=package

cmd/kubeadm/app/apis/kubeadm/v1alpha3/types.go

@@ -234,9 +234,7 @@ type LocalEtcd struct {
 
 // ExternalEtcd describes an external etcd cluster
 type ExternalEtcd struct {
-
-	// Endpoints of etcd members. Useful for using external etcd.
-	// If not provided, kubeadm will run etcd in a static pod.
+	// Endpoints of etcd members. Required for ExternalEtcd.
 	Endpoints []string `json:"endpoints"`
 	// CAFile is an SSL Certificate Authority file used to secure etcd communication.
 	CAFile string `json:"caFile"`