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 inventories: The 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 by deleting the whole repository.
• In Git systems, user permissions are often set on repository level. This is useful if you need to restrict visibility of individual projects/inventories when your users directly access the Git system. Note that inside the nevisAdmin 4 GUI application, project/inventory permissions are configured and enforced independently of Git. Whether or not application users themselves have permissions in Git is thus irrelevant. See also the section Permissions: Technical User vs. Application Users below.

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. To avoid "empty updates" (see below), create a long-lived branch for each project.
• 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:
  • With time, version control operations such as importing and publishing may become slower.
  • The risk for human errors increases. For example, someone may inadvertently merge or delete a branch containing data that is still needed.
• 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 (see Check out of older project and inventory versions).
  • The git revert operation will revert the data of all projects/inventories in the same repository, which is usually not desired.
• Usability will suffer. This is best explained by means of an example:
  • The unrelated projects A and B are both connected to the same Git repository on the master branch.
    • Their repository paths have to be different, for example, /project-A and /project-B.
  • You publish (push) project A to Git. This works fine and creates a new commit ID in Git.
  • You publish (push) project B to Git: This is not possible because project B's checkout is "behind". First, update (pull) the project.
    • The update (pull) is necessary 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.
  • Now, publish project B to Git and a new commit ID is created.
  • After this, project A is "behind" and an empty update cycle for project A is necessary.
  • The empty update cycles are bad for user experience and may cause data loss in some situations.

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 uses 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 has write permissions for all repositories used by nevisAdmin 4 projects and inventories.
  • The name of the technical user does not matter. You establish a connection between a nevisAdmin 4 instance and the technical user by registering the public SSH RSA key from the nevisAdmin 4 host for this technical user on the repository management system.

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 is required 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.

note

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

3. 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.

HTTPS Connection Setup

Only one user/password pair is supported. If you want to employ multiple Git hosts, then you have to use the same technical user and password for all hosts.

Avoid using plain text passwords in configuration files. For more information, see Deployment via SSH > Protecting Passwords or Other Settings.

Define the Git connection user and password in the nevisadmin4.yml file, as follows:

nevisadmin:
  git:
    tls:
      username: <git-user>
      password: <git-user-password>

Setup Trust

The HTTPS connection to Git will fail if the server certificate cannot be trusted, for example, because you use a self-signed certificate or a certificate issued by a non-official CA. In such a case, the nevisAdmin 4 log will look like this:

caused by sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target at sun.security.provider.certpath.SunCertPathBuilder.build(SunCertPathBuilder.java:141)

To establish trust, you need to configure the default Java truststore. Proceed as follows:

1. Import the certificate of the issuing CA into a Java keystore file (JKS or PKCS12 format).

2. Store this file somewhere on your nevisAdmin 4 server (for example: /var/opt/nevisadmin4/conf/truststore.jks).

3. Then add -Djavax.net.ssl.trustStore to the JAVA_OPTS variable in the env.conf file:

   JAVA_OPTS='... -Djavax.net.ssl.trustStore=/var/opt/nevisadmin4/conf/truststore.jks'

Enabling Version Control for Configuration Projects

See Creating a Project.

Enabling 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 is required. This user has 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 (git pull) or publish (git push). See Editing Project Permissions and Editing Inventory Permissions.

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.