XTesting/kubespray/docs/integration.md

   1 # Kubespray (kubespray) in own ansible playbooks repo
   2
   3 1. Fork [kubespray repo](https://github.com/kubernetes-sigs/kubespray) to your personal/organisation account on github.
   4    Note:
   5      * All forked public repos at github will be also public, so **never commit sensitive data to your public forks**.
   6      * List of all forked repos could be retrieved from github page of original project.
   7
   8 2. Add **forked repo** as submodule to desired folder in your existent ansible repo (for example 3d/kubespray):
   9   ```git submodule add https://github.com/YOUR_GITHUB/kubespray.git kubespray```
  10   Git will create `.gitmodules` file in your existent ansible repo:
  11
  12    ```ini
  13    [submodule "3d/kubespray"]
  14          path = 3d/kubespray
  15          url = https://github.com/YOUR_GITHUB/kubespray.git
  16    ```
  17
  18 3. Configure git to show submodule status:
  19 ```git config --global status.submoduleSummary true```
  20
  21 4. Add *original* kubespray repo as upstream:
  22 ```cd kubespray && git remote add upstream https://github.com/kubernetes-sigs/kubespray.git```
  23
  24 5. Sync your master branch with upstream:
  25
  26    ```ShellSession
  27       git checkout master
  28       git fetch upstream
  29       git merge upstream/master
  30       git push origin master
  31    ```
  32
  33 6. Create a new branch which you will use in your working environment:
  34 ```git checkout -b work```
  35     ***Never*** use master branch of your repository for your commits.
  36
  37 7. Modify path to library and roles in your ansible.cfg file (role naming should be unique, you may have to rename your existent roles if they have same names as kubespray project),
  38    if you had roles in your existing ansible project before, you can add the path to those separated with `:`:
  39
  40 8. ```ini
  41    ...
  42    library       = ./library/:3d/kubespray/library/
  43    roles_path    = ./roles/:3d/kubespray/roles/
  44    ...
  45    ```
  46
  47 9. Copy and modify configs from kubespray `group_vars` folder to corresponding `group_vars` folder in your existent project.
  48 You could rename *all.yml* config to something else, i.e. *kubespray.yml* and create corresponding group in your inventory file, which will include all hosts groups related to kubernetes setup.
  49
  50 10. Modify your ansible inventory file by adding mapping of your existent groups (if any) to kubespray naming.
  51     For example:
  52
  53     ```ini
  54       ...
  55       #Kargo groups:
  56       [kube_node:children]
  57       kubenode
  58
  59       [k8s_cluster:children]
  60       kubernetes
  61
  62       [etcd:children]
  63       kubemaster
  64       kubemaster-ha
  65
  66       [kube_control_plane:children]
  67       kubemaster
  68       kubemaster-ha
  69
  70       [kubespray:children]
  71       kubernetes
  72       ```
  73
  74       * Last entry here needed to apply kubespray.yml config file, renamed from all.yml of kubespray project.
  75
  76 11. Now you can include kubespray tasks in you existent playbooks by including cluster.yml file:
  77
  78      ```yml
  79      - name: Import kubespray playbook
  80        ansible.builtin.import_playbook: 3d/kubespray/cluster.yml
  81      ```
  82
  83      Or your could copy separate tasks from cluster.yml into your ansible repository.
  84
  85 12. Commit changes to your ansible repo. Keep in mind, that submodule folder is just a link to the git commit hash of your forked repo.
  86 When you update your "work" branch you need to commit changes to ansible repo as well.
  87 Other members of your team should use ```git submodule sync```, ```git submodule update --init``` to get actual code from submodule.
  88
  89 ## Contributing
  90
  91 If you made useful changes or fixed a bug in existent kubespray repo, use this flow for PRs to original kubespray repo.
  92
  93 1. Sign the [CNCF CLA](https://git.k8s.io/community/CLA.md).
  94
  95 2. Change working directory to git submodule directory (3d/kubespray).
  96
  97 3. Setup desired user.name and user.email for submodule.
  98 If kubespray is only one submodule in your repo you could use something like:
  99 ```git submodule foreach --recursive 'git config user.name "First Last" && git config user.email "your-email-address@used.for.cncf"'```
 100
 101 4. Sync with upstream master:
 102
 103    ```ShellSession
 104     git fetch upstream
 105     git merge upstream/master
 106     git push origin master
 107      ```
 108
 109 5. Create new branch for the specific fixes that you want to contribute:
 110 ```git checkout -b fixes-name-date-index```
 111 Branch name should be self explaining to you, adding date and/or index will help you to track/delete your old PRs.
 112
 113 6. Find git hash of your commit in "work" repo and apply it to newly created "fix" repo:
 114
 115      ```ShellSession
 116      git cherry-pick <COMMIT_HASH>
 117      ```
 118
 119 7. If you have several temporary-stage commits - squash them using [```git rebase -i```](https://eli.thegreenplace.net/2014/02/19/squashing-github-pull-requests-into-a-single-commit)
 120 Also you could use interactive rebase (```git rebase -i HEAD~10```) to delete commits which you don't want to contribute into original repo.
 121
 122 8. When your changes is in place, you need to check upstream repo one more time because it could be changed during your work.
 123 Check that you're on correct branch:
 124 ```git status```
 125 And pull changes from upstream (if any):
 126 ```git pull --rebase upstream master```
 127
 128 9. Now push your changes to your **fork** repo with ```git push```. If your branch doesn't exists on github, git will propose you to use something like ```git push --set-upstream origin fixes-name-date-index```.
 129
 130 10. Open you forked repo in browser, on the main page you will see proposition to create pull request for your newly created branch. Check proposed diff of your PR. If something is wrong you could safely delete "fix" branch on github using ```git push origin --delete fixes-name-date-index```, ```git branch -D fixes-name-date-index``` and start whole process from the beginning.
 131 If everything is fine - add description about your changes (what they do and why they're needed) and confirm pull request creation.