Jump to contentJump to page navigation: previous page [access key p]/next page [access key n]
documentation.suse.com / Documentation / Deployment Guide using Cloud Lifecycle Manager / Cloud Installation / Using Git for Configuration Management
Applies to SUSE OpenStack Cloud 9

22 Using Git for Configuration Management

  

In SUSE OpenStack Cloud 9, a local git repository is used to track configuration changes; the Configuration Processor (CP) uses this repository. Use of a git workflow means that your configuration history is maintained, making rollbacks easier and keeping a record of previous configuration settings. The git repository also provides a way for you to merge changes that you pull down as “upstream” updates (that is, updates from SUSE). It also allows you to manage your own configuration changes.

The git repository is installed by the Cloud Lifecycle Manager on the Cloud Lifecycle Manager node.

22.1 Initialization on a new deployment

  

On a system new to SUSE OpenStack Cloud 9, the Cloud Lifecycle Manager will prepare a git repository under ~/openstack. The Cloud Lifecycle Manager provisioning runs the ardana-init-deployer script automatically. This calls ansible-playbook -i hosts/localhost git-00-initialise.yml.

As a result, the ~/openstack directory is initialized as a git repo (if it is empty). It is initialized with four empty branches:

ardana

This holds the upstream source code corresponding to the contents of the ~/openstack directory on a pristine installation. Every source code release that is downloaded from SUSE is applied as a fresh commit to this branch. This branch contains no customization by the end user.

site

This branch begins life as a copy of the first ardana drop. It is onto this branch that you commit your configuration changes. It is the branch most visible to the end user.

ansible

This branch contains the variable definitions generated by the CP that our main ansible playbooks need. This includes the verb_hosts file that describes to ansible what servers are playing what roles. The ready-deployment playbook takes this output and assembles a ~/scratch directory containing the ansible playbooks together with the variable definitions in this branch. The result is a working ansible directory ~/scratch/ansible/next/ardana/ansible from which the main deployment playbooks may be successfully run.

cp-persistent

This branch contains the persistent state that the CP needs to maintain. That state is mostly the assignment of IP addresses and roles to particular servers. Some operational procedures may involve editing the contents of this branch: for example, retiring a machine from service or repurposing it.

Two temporary branches are created and populated at run time:

staging-ansible

This branch hosts the most recent commit that will be appended to the Ansible branch.

staging-cp-persistent

This branch hosts the most recent commit that will be appended to the cp-persistent branch.

Note
Note

The information above provides insight into the workings of the configuration processor and the git repository. However, in practice you can simply follow the steps below to make configuration changes.

22.2 Updating any configuration, including the default configuration

  

When you need to make updates to a configuration you must:

  1. Check out the site branch. You may already be on that branch. If so, git will tell you that and the command will leave you there. 

    git checkout site

  2. Edit the YAML file or files that contain the configuration you want to change.

  3. Commit the changes to the site branch. 

    git add -A
git commit -m "your commit message goes here in quotes"

    If you want to add a single file to your git repository, you can use the command below, as opposed to using git add -A. 

    git add PATH_TO_FILE

    For example, if you made a change to your servers.yml file and wanted to only commit that change, you would use this command: 

    git add ~/openstack/my_cloud/definition/data/servers.yml

  4. To produce the required configuration processor output from those changes. Review the output files manually if required, run the configuration processor: 

    cd ~/openstack/ardana/ansible
ansible-playbook -i hosts/localhost config-processor-run.yml

  5. Ready the deployment area 

    ansible-playbook -i hosts/localhost ready-deployment.yml

  6. Run the deployment playbooks from the resulting scratch directory. 

    cd ~/scratch/ansible/next/ardana/ansible
ansible-playbook -i hosts/verb_hosts site.yml

22.3 Resolving Git merge conflicts

  

When you make changes, SUSE OpenStack Cloud attempts to incorporate new or updated configuration information on top of your existing environment. However, with some changes to your environment, SUSE OpenStack Cloud cannot automatically determine whether to keep your changes or drop them in favor of the new or updated configurations. This will result in merge conflicts, and it will be up to you to manually resolve the conflicts before you can proceed. This is common, but it can be confusing. Git provides a way to resolve these situations.

This section gives an overview of how to approach the issue of merge conflicts, showing general procedures for determining where the conflict is occurring, alternative methods for resolution, and a fallback procedure for the case where the resolution goes wrong and you need to start changes from the beginning.

For a general overview of how SUSE OpenStack Cloud uses Git, see the introductory article Chapter 22, Using Git for Configuration Management. In particular, note how the site branch is the one most used by the end-user, while the ardana branch contains the "upstream" source code corresponding to the contents of the ~/openstack directory on a pristine fresh installation.

22.3.1 Identifying the occurrence of a merge conflict

  

If you get a merge conflict, you will observe output similar to the following on the console: 

Auto-merging ardana/ansible/roles/nova-compute-esx/defaults/main.yml
Auto-merging ardana/ansible/roles/nova-common/templates/nova.conf.j2
CONFLICT (content): Merge conflict in ardana/ansible/roles/nova-common/templates/nova.conf.j2
Auto-merging ardana/ansible/roles/nova-cli/tasks/availability_zones.yml
Auto-merging ardana/ansible/roles/nova-api/templates/api-paste.ini.j2

22.3.2 Examining Conflicts

  

Use git status to discover the source of the problem: 

...
        new file:   tech-preview/entry-scale-kvm-mml/data/swift/swift_config.yml
        modified:   tech-preview/mid-scale/README.md
        modified:   tech-preview/mid-scale/data/control_plane.yml

Unmerged paths:
  (use "git add/rm <file>..." as appropriate to mark resolution)

        both modified:   ardana/ansible/roles/nova-common/templates/nova.conf.j2

Edit the file ardana/ansible/roles/nova-common/templates/nova.conf.j2 to see the conflict markers: 

[neutron]
admin_auth_url = {{ neutron_admin_auth_url }}
admin_password = {{ neutron_admin_password }}
admin_tenant_name = {{ neutron_admin_tenant_name }}
admin_username = {{ neutron_admin_username }}
<<<<<<<HEAD
metadata_proxy_shared_secret = top_secret_password111
=======
metadata_proxy_shared_secret = {{ neutron_metadata_proxy_shared_secret }}
>>>>>>> ardana
neutron_auth_strategy = keystone
neutron_ca_certificates_file = /etc/ssl/certs/ca-certificates.crt
service_metadata_proxy = True

This indicates that SUSE OpenStack Cloud 9is trying to set the value of metadata_proxy_shared_secret to be {{ neutron_metadata_proxy_shared_secret }} whereas previously you have set its value to top_secret_password111.

22.3.3 Examining differences between your current version and the previous upstream version

  

Typically, the previous upstream version will be the last-but-one commit on the ardana branch. This version will have been created during the initial installation of your cloud (or perhaps during a previous upgrade or configuration change). So in total, there are three significant versions of the file:

  • The previous "upstream" version on the ardana branch.

  • Your current version on the site branch.

  • The new "upstream" version on the ardana branch.

You can identify the commit number of the previous "upstream" version using git merge-base. 

tux > git merge-base ardana site
2eda1df48e2822533c50f80f5bfd7a9d788bdf73

And then use git log to see where this commit occurs in the history of the ardana branch. 

tux > git log ardana --
commit 22cfa83f3526baf30b3697e971a712930f86f611
Author: Openstack git user <openstack@example.com>
Date:   Mon Jan 18 00:30:33 2018 +0000

    New drop

commit 2eda1df48e2822533c50f80f5bfd7a9d788bdf73
Author: Openstack git user <openstack@example.com>
Date:   Sun Jan 17 19:14:01 2018 +0000

    New drop

In this instance, we can see that the relevant commit is in fact the last-but-one commit. We can use the simplified name ardana^1 to identify that commit. 

tux > git diff ardana^1 HEAD -- ardana/ansible/roles/nova-common/templates/nova.conf.j2

In the diff output, you should be able to see how you changed the value for metadata_proxy_shared_secret from unset to top_secret_password111: 

tux > diff --git a/ardana/ansible/roles/nova-common/templates/nova.conf.j2 b/ardana/ansible/roles/nova-common/templates/nova.conf.j2
index 597a982..05cb07c 100644
--- a/ardana/ansible/roles/nova-common/templates/nova.conf.j2
+++ b/ardana/ansible/roles/nova-common/templates/nova.conf.j2
@@ -132,7 +132,7 @@ admin_auth_url = {{ neutron_admin_auth_url }}
 admin_password = {{ neutron_admin_password }}
 admin_tenant_name = {{ neutron_admin_tenant_name }}
 admin_username = {{ neutron_admin_username }}
-metadata_proxy_shared_secret = unset
+metadata_proxy_shared_secret = top_secret_password111
 neutron_auth_strategy = keystone
 neutron_ca_certificates_file = /etc/ssl/certs/ca-certificates.crt
 service_metadata_proxy = True

22.3.4 Examining differences between your current version and the new upstream version

  

To compare your change with the new upstream version from SUSE OpenStack Cloud 9 on the ardana branch you can use git diff HEAD ardana -- <<path/to/file>>: 

tux > git diff HEAD ardana -- ardana/ansible/roles/nova-common/templates/nova.conf.j2

In the extract of output below, you can see your value top_secret_password111 and the new value {{ neutron_metadata_proxy_shared_secret }} that SUSE OpenStack Cloud 9 wants to set. 

..
 admin_username = {{ neutron_admin_username }}
-metadata_proxy_shared_secret = top_secret_password111
+metadata_proxy_shared_secret = {{ neutron_metadata_proxy_shared_secret }}
 neutron_auth_strategy = keystone
 neutron_ca_certificates_file = /etc/ssl/certs/ca-certificates.crt

22.3.5 Examining differences between the new upstream version and the previous upstream version

  

To compare the new upstream version from SUSE OpenStack Cloud 9 with the previous upstream version from your initial install (or previous change): 

tux > git diff $(git merge-base ardana HEAD) ardana -- ardana/ansible/roles/nova-common/templates/nova.conf.j2

In the extract of output below, you can see the new upstream value {{ neutron_metadata_proxy_shared_secret }} that SUSE OpenStack Cloud 9 wants to set and the previous upstream value unset. 

 admin_password = {{ neutron_admin_password }}
 admin_tenant_name = {{ neutron_admin_tenant_name }}
 admin_username = {{ neutron_admin_username }}
-metadata_proxy_shared_secret = unset
+metadata_proxy_shared_secret = {{ neutron_metadata_proxy_shared_secret }}
 neutron_auth_strategy = keystone
 neutron_ca_certificates_file = /etc/ssl/certs/ca-certificates.crt

22.3.6 Using stage markers to view clean versions of files (without conflict markers)

  

You can use the git show command with stage markers to view files without having conflict markers embedded in them. Stage 1 is the previous upstream version (:1), stage 2 is your current version (:2) while stage 3 is the new upstream version (:3).

Stage 1 

tux > git show :1:ardana/ansible/roles/nova-common/templates/nova.conf.j2
...
admin_username = {{ neutron_admin_username }}
metadata_proxy_shared_secret = unset
neutron_auth_strategy = keystone
neutron_ca_certificates_file = /etc/ssl/certs/ca-certificates.crt
...

Stage 2 

tux > git show :2:ardana/ansible/roles/nova-common/templates/nova.conf.j2
...
admin_username = {{ neutron_admin_username }}
metadata_proxy_shared_secret = top_secret_password111
neutron_auth_strategy = keystone
neutron_ca_certificates_file = /etc/ssl/certs/ca-certificates.crt
...

Stage 3 

tux > git show :3:ardana/ansible/roles/nova-common/templates/nova.conf.j2
...
admin_username = {{ neutron_admin_username }}
metadata_proxy_shared_secret = {{ neutron_metadata_proxy_shared_secret }}
neutron_auth_strategy = keystone
neutron_ca_certificates_file = /etc/ssl/certs/ca-certificates.crt
...

22.3.7 Resolving the conflict

  

There are two approaches to resolving the conflict:

  1. Edit the merged file containing the conflict markers, keeping the change you want to preserve and removing the conflict markers and any changes you want to discard.

  2. Take the new upstream version of the file and re-apply any changes you would like to keep from your current version.

22.3.8 Resolving the conflict - editing the file containing the conflict markers

  

Edit the file ardana/ansible/roles/nova-common/templates/nova.conf.j2 and if you want to maintain your change, then delete the lines in bold below: 

[neutron]
admin_auth_url = {{ neutron_admin_auth_url }}
admin_password = {{ neutron_admin_password }}
admin_tenant_name = {{ neutron_admin_tenant_name }}
admin_username = {{ neutron_admin_username }}
<<<<<<<HEAD
metadata_proxy_shared_secret = top_secret_password111
=======
metadata_proxy_shared_secret = {{ neutron_metadata_proxy_shared_secret }}
>>>>>>> ardana
neutron_auth_strategy = keystone
neutron_ca_certificates_file = /etc/ssl/certs/ca-certificates.crt
service_metadata_proxy = True

Your file should now look like this: 

[neutron]
admin_auth_url = {{ neutron_admin_auth_url }}
admin_password = {{ neutron_admin_password }}
admin_tenant_name = {{ neutron_admin_tenant_name }}
admin_username = {{ neutron_admin_username }}
metadata_proxy_shared_secret = top_secret_password111
neutron_auth_strategy = keystone
neutron_ca_certificates_file = /etc/ssl/certs/ca-certificates.crt
service_metadata_proxy = True

22.3.9 Resolving the conflict - re-applying your changes to new upstream version

  

Create a copy of the new upstream version (see Stage 3 above) in your working directory: 

tux > git show :3:ardana/ansible/roles/nova-common/templates/nova.conf.j2 > \
ardana/ansible/roles/nova-common/templates/nova.conf.j2

Now edit the file ardana/ansible/roles/nova-common/templates/nova.conf.j2 and manually re-apply the changes you want.

22.3.10 Completing the merge procedure

  

You may want to check that the changes you have applied are correct. Compare the new upstream version with the version in your working directory: 

tux > git diff ardana -- ardana/ansible/roles/nova-common/templates/nova.conf.j2

If you are happy with the resolution, you can stage your changes using: 

tux > git add ardana/ansible/roles/nova-common/templates/nova.conf.j2

Apply the above steps to all the merge conflicts you encounter, and when you have them resolved to your satisfaction, complete the merge: 

git commit -m "complete merge"

22.3.11 Recovering from Errors

  

If you make a mistake during the resolution process, you can return your working directory to a clean copy of the site branch using: 

tux > git reset --hard

If the new upstream version contains files that did not exist in the previous version, these files will be left behind - you can see them using git status. To clean up these files, remove them and then reset: 

tux > git rm -rf ardana
tux > git reset --hard

Alternatively, you can use git stash to save these files to a transient stash queue.