sigs.k8s.io/cluster-api-provider-aws@v1.5.5/docs/book/src/development/development.md (about) 1 # Developer Guide 2 3 ## Initial setup for development environment 4 5 ### Install prerequisites 6 7 1. Install [go][go] 8 - Get the latest patch version for go v1.17. 9 2. Install [jq][jq] 10 - `brew install jq` on macOS. 11 - `chocolatey install jq` on Windows. 12 - `sudo apt install jq` on Ubuntu Linux. 13 3. Install [KIND][kind] 14 - `GO111MODULE="on" go get sigs.k8s.io/kind@v0.12.0`. 15 4. Install [Kustomize][kustomize] 16 - [install instructions](https://kubectl.docs.kubernetes.io/installation/kustomize/) 17 5. Install [envsubst][envsubst] 18 6. Install make. 19 7. Install direnv 20 - `brew install direnv` on macOS. 21 22 ### Get the source 23 24 Fork the [cluster-api-provider-aws repo](https://github.com/kubernetes-sigs/cluster-api-provider-aws): 25 26 ```bash 27 cd "$(go env GOPATH)"/src 28 mkdir sigs.k8s.io 29 cd sigs.k8s.io/ 30 git clone git@github.com:<GITHUB USERNAME>/cluster-api-provider-aws.git 31 cd cluster-api-provider-aws 32 git remote add upstream git@github.com:kubernetes-sigs/cluster-api-provider-aws.git 33 git fetch upstream 34 ``` 35 36 ### Build clusterawsadm 37 38 Build `clusterawsadm` in `cluster-api-provider-aws`: 39 40 ```bash 41 cd "$(go env GOPATH)"/src/sigs.k8s.io/cluster-api-provider-aws 42 make clusterawsadm 43 mv ./bin/clusterawsadm /usr/local/bin/clusterawsadm 44 ``` 45 46 ### Setup AWS Environment 47 48 Create bootstrap file and bootstrap IAM roles and policies using `clusterawsadm` 49 50 ```bash 51 $ cat config-bootstrap.yaml 52 53 apiVersion: bootstrap.aws.infrastructure.cluster.x-k8s.io/v1beta1 54 kind: AWSIAMConfiguration 55 spec: 56 bootstrapUser: 57 enable: true 58 59 $ clusterawsadm bootstrap iam create-cloudformation-stack 60 Attempting to create AWS CloudFormation stack cluster-api-provider-aws-sigs-k8s-io 61 ``` 62 63 #### Customizing the bootstrap permission 64 65 The IAM permissions can be customized by using a configuration file with **clusterawsadm**. For example, to create the default IAM role for use with managed machine pools: 66 67 ```bash 68 $ cat config-bootstrap.yaml 69 apiVersion: bootstrap.aws.infrastructure.cluster.x-k8s.io/v1beta1 70 kind: AWSIAMConfiguration 71 spec: 72 bootstrapUser: 73 enable: true 74 eks: 75 iamRoleCreation: false # Set to true if you plan to use the EKSEnableIAM feature flag to enable automatic creation of IAM roles 76 managedMachinePool: 77 disable: false # Set to false to enable creation of the default node role for managed machine pools 78 ``` 79 80 Use the configuration file to create the additional IAM role: 81 82 ```bash 83 $ ./bin/clusterawsadm bootstrap iam create-cloudformation-stack --config=config-bootstrap.yaml 84 Attempting to create AWS CloudFormation stack cluster-api-provider-aws-sigs-k8s-io 85 ``` 86 87 > If you don't plan on using EKS then see the [documentation on disabling EKS support](../topics/eks/disabling.md). 88 89 #### Sample Output 90 91 When creating the CloudFormation stack using **clusterawsadm** you will see output similar to this: 92 93 ```bash 94 Following resources are in the stack: 95 96 Resource |Type |Status 97 AWS::IAM::Group |cluster-api-provider-aws-s-AWSIAMGroupBootstrapper-ME9XZVCO2491 |CREATE_COMPLETE 98 AWS::IAM::InstanceProfile |control-plane.cluster-api-provider-aws.sigs.k8s.io |CREATE_COMPLETE 99 AWS::IAM::InstanceProfile |controllers.cluster-api-provider-aws.sigs.k8s.io |CREATE_COMPLETE 100 AWS::IAM::InstanceProfile |nodes.cluster-api-provider-aws.sigs.k8s.io |CREATE_COMPLETE 101 AWS::IAM::ManagedPolicy |arn:aws:iam::xxx:policy/control-plane.cluster-api-provider-aws.sigs.k8s.io |CREATE_COMPLETE 102 AWS::IAM::ManagedPolicy |arn:aws:iam::xxx:policy/nodes.cluster-api-provider-aws.sigs.k8s.io |CREATE_COMPLETE 103 AWS::IAM::ManagedPolicy |arn:aws:iam::xxx:policy/controllers.cluster-api-provider-aws.sigs.k8s.io |CREATE_COMPLETE 104 AWS::IAM::Role |control-plane.cluster-api-provider-aws.sigs.k8s.io |CREATE_COMPLETE 105 AWS::IAM::Role |controllers.cluster-api-provider-aws.sigs.k8s.io |CREATE_COMPLETE 106 AWS::IAM::Role |eks-controlplane.cluster-api-provider-aws.sigs.k8s.io |CREATE_COMPLETE 107 AWS::IAM::Role |eks-nodegroup.cluster-api-provider-aws.sigs.k8s.io |CREATE_COMPLETE 108 AWS::IAM::Role |nodes.cluster-api-provider-aws.sigs.k8s.io |CREATE_COMPLETE 109 AWS::IAM::User |bootstrapper.cluster-api-provider-aws.sigs.k8s.io |CREATE_COMPLETE 110 ``` 111 112 ### Set Environment Variables 113 114 - Create a security credentials in the `bootstrapper.cluster-api-provider-aws.sigs.k8s.io` IAM user that is created by cloud-formation stack and copy the `AWS_ACCESS_KEY_ID` and `AWS_SECRETS_ACCESS_KEY`. 115 (Or use admin user credentials instead) 116 117 - Set AWS_B64ENCODED_CREDENTIALS environment variable 118 119 ```bash 120 export AWS_ACCESS_KEY_ID=AKIATEST 121 export AWS_SECRET_ACCESS_KEY=TESTTEST 122 export AWS_REGION=eu-west-1 123 export AWS_B64ENCODED_CREDENTIALS=$(clusterawsadm bootstrap credentials encode-as-profile) 124 ``` 125 126 ## Running local management cluster for development 127 128 Before the next steps, make sure [initial setup for development environment][Initial-setup-for-development-environment] steps are complete. 129 130 [Initial-setup-for-development-environment]: ../development/development.html#initial-setup-for-development-environment 131 132 There are two ways to build aws manager from local cluster-api-provider-aws source and run it in local kind cluster: 133 134 ### Option 1: Setting up Development Environment with Tilt 135 136 [Tilt][tilt] is a tool for quickly building, pushing, and reloading Docker containers as part of a Kubernetes deployment. 137 Many of the Cluster API engineers use it for quick iteration. Please see our [Tilt instructions][Tilt instructions] to get started. 138 139 [tilt]: https://tilt.dev 140 [Tilt instructions]: ../development/tilt-setup.md 141 142 ### Option 2: The Old-fashioned way 143 144 Running cluster-api and cluster-api-provider-aws controllers in a kind cluster: 145 146 1. Create a local kind cluster 147 - `kind create cluster` 148 2. Install core cluster-api controllers (the version must match the cluster-api version in [go.mod][go.mod]) 149 - `clusterctl init --core cluster-api:v0.3.16 --bootstrap kubeadm:v0.3.16 --control-plane kubeadm:v0.3.16` 150 3. Build cluster-api-provider-aws docker images 151 - `make e2e-image` 152 4. Release manifests under `./out` directory 153 - `RELEASE_TAG="e2e" make release-manifests` 154 5. Apply the manifests 155 - `kubectl apply -f ./out/infrastructure.yaml` 156 157 [go]: https://golang.org/doc/install 158 [jq]: https://stedolan.github.io/jq/download/ 159 [go.mod]: https://github.com/kubernetes-sigs/cluster-api-provider-aws/blob/master/go.mod 160 [kind]: https://sigs.k8s.io/kind 161 [kustomize]: https://github.com/kubernetes-sigs/kustomize 162 [kustomizelinux]: https://github.com/kubernetes-sigs/kustomize/blob/master/docs/INSTALL.md 163 [envsubst]: https://github.com/a8m/envsubst