Skip to main content
Version: 4.5.x LTS

Git Setup and Best Practices

Introduction and Best Practices

For versioning your configuration projects and infrastructure inventories, nevisAdmin 4 provides integration with the Git version control system.

Although Git is recommended to benefit from version control, it is optional if you use classic deployment. For Kubernetes deployment, Git is always required.

Your Git system is used to store the following information:

  • Configuration projects Patterns and variables are stored in YAML form, file attachments in binary form.
  • Infrastructure inventoriesThe inventory YAML file is stored as is. Secret values or secret attachments are not stored in Git. See Working with Secrets in the User Guide.
  • Generated component configurations (Kubernetes deployment only) Nevis component configurations generated by nevisAdmin 4 are stored in a deployment repository. The files in this repository are then consumed by Docker containers running nevisProxy, nevisAuth and so on.

For more details on what is stored exactly, see the File formats reference.

How Many Git Repositories Do I Need?​

The preferred approach is to create various separate Git repositories:

  • One repository per configuration project.
  • One repository per infrastructure inventory.
  • When using Kubernetes, one [deployment repository] per inventory.

There is one exception to the above: If you work with (short-lived) branches, you will import these as additional projects/inventories into nevisAdmin 4 from the same repository. This is fine because branch/merge workflows in Git require the data to be in the same repository.

This separate repository approach is recommended for most customers.

Discussion and Alternative Approaches​

The separate repository approach has the following advantages:

  • You get a clean commit log (audit trail) in each of the repositories, so for each project/inventory.
  • If you no longer need a project or inventory, you can easily clean up all data belonging to it: Just delete the whole repository.
  • In Git systems, user permissions are often set on repository level. This is useful if you need to restrict visibility of in

In some organizations, the recommended approach is not feasible. If so, you can combine things so that fewer repositories are needed. Here are some examples:

  • One repository for all projects, each project has a different repository path.

  • Similarly, one or two repositories for your inventories, for example, one for DEV/TEST and one for PRE-PROD/PROD inventories.

  • When using Kubernetes, you can use the same repository for an inventory and for its deployed Kubernetes component configurations, each on a separate long-lived branch.

  • All of the above combined: A single repository for everything. This is not recommended.

The combined approach has the following drawbacks:

  • You will have fewer repositories, but each of these will be larger in size and complexity:
  • You lose the advantages of the separate repository approach mentioned above. The "Empty Updates" Problem

It is possible to connect multiple projects or inventories to the same remote branch in the same Git repository.

This is not recommended for the following reasons:

  • In some cases, git revert is useful to roll back a single project or inventory to a previous commit .
  • Usability will suffer. This is best explained by means of an example:
    • Their repository paths have to be different, for example, /project-A and /project-B.
    • The update (pull) is needed because Git always requires the latest state before you can publish (push).
    • The update will be "empty", because in this example, only files in /project-A were changed.

To avoid the "empty updates" problem, connect each project and inventory to a different, long-lived branch. These branches are unrelated and should never be merged.

Prerequisites

The Git connection to your repository must use the SSH protocol. The following sections explain how to configure SSH so that nevisAdmin 4 can safely connect to the Git system.

Git System​

  • A Git repository management system is installed and ready to use. Examples of such repository management systems are BitBucket, GitLab, or Gitea.
  • A technical user for nevisAdmin 4 is available on the repository management system. This user must have write permissions for all repositories used by nevisAdmin 4 projects and inventories.

nevisAdmin 4 can import/update project configurations and inventory infrastructures from Git and publish them to Git.

Parallel modification of the same project or inventory, both inside nevisAdmin 4 and in the remote Git repository, is not supported because conflict resolution is not implemented.

Attaching multiple nevisAdmin 4 instances to the same Git repository is supported, but make sure that only one of the instances publishes to the same Git repository branch. All others should not publish to that repository. Note that it is fine if multiple nevisAdmin 4 instances publish to the same Git system, just not to the same repository branch within that system.

It is possible, but not recommended, to publish multiple unrelated projects/inventories into the same repository by using a different repository path for each one. This has the following drawback: In Git, commits, branches, and so on, are global for the repository, meaning that it will be difficult to distinguish changes in one project from changes in other projects. The same holds for inventories.

nevisAdmin 4 Host​

An RSA key pair must be available on the machine where nevisAdmin 4 runs. The default location is /home/nvbuser/.ssh/ . nvbuser is the run-time user of the nevisAdmin 4 application.

The new OpenSSH private key format is currently not supported.

If the private key is protected by a passphrase, you can configure it in nevisadmin4.yml.

Also, it is possible to change the path to the private key file. nevisAdmin 4 reads the known_hosts file and the public key file (ending in .pub) from the same location as the private key file.

To configure a different path for these files or to set the passphrase, use the following properties in /var/opt/nevisadmin4/conf/nevisadmin4.yml:

nevisadmin:
  git:
    ssh:
      privatekey:
        file: <custom path>/id_rsa
        passphrase: <passphrase for the private key file>

SSH Connection Setup

Proceed as follows to set up the SSH connection.

Git System​

  1. Get the public SSH RSA key from the shell on the nevisAdmin 4 host. The default file location is: /home/nvbuser/.ssh/id_rsa.pub Copy the contents to your clipboard.
  2. In the repository management system, register this public key for the nevisAdmin 4 technical user.

nevisAdmin 4 Host​

  1. From the command line of the nevisAdmin 4 host, make sure that the Git system's host and port entry is added to the known_hosts file of the nevisAdmin 4 runtime user.
  2. Try to establish an SSH connection to the repository management system host on its SSH port. For example, if the system is available at nevisadmin4.siven.ch on port 2244, run the following commands:
su nvbuser
ssh -o HostKeyAlgorithms=ssh-rsa [email protected] -p 2244
  1. On the console, accept that the host is permanently added to the known_hosts file.

To avoid the interactive console question, SSH can automatically update the known_hosts file. Therefore, specify -o StrictHostKeyChecking=no in the above command. 4. If a Permission denied error occurs after adding the host, you can ignore it for now.

Enable Version Control for Configuration Projects

See Creating a Project.

Enable Version Control for Inventories

See Creating an Inventory.

Permissions: Technical User vs. Application Users

There are two levels of permissions:

  • On the Git system side, a single technical user must be available. This user must have access to all nevisAdmin 4 related projects and inventories. Only Git administrators/system operators are expected to know the credentials of this user.
  • On the nevisAdmin 4 application side, project and inventory permissions govern which end users can update ".

The user that is logged in to nevisAdmin 4 when publishing changes is set as the committer for the change in Git. However, this user has no impact on the permissions in the Git system.