Best Practices

Introduction¶

This document details the best practices guidelines for the tools and systems managed by CIA Linux. Contributions and changes to systems or platforms should match these practices whenever possible.

Red Hat Enterprise Linux¶

Target Audience: Users with root access to a CIA managed Red Hat Server, or anyone deploying applications that require root access in order to be installed.

Software and Patching¶

Beyond the obvious benefits of keeping our systems up to date, a regular and predictable patching schedule will help us to minimise any risks introduced to our servers (such as compatibility or configuration issues) by patching. Keeping the OS and installed software up-to-date is a basic security requirement and is required in order to maintain support with Red Hat.

How and When?¶

Content is managed by Red Hat Satellite Server. This content is synced regularly from upstream repositories (both Red Hat and 3rd party) and published/promoted to different server environments in a weekly staged process once every month.

After content is made available to a Lifecycle Environment, the patching process begins, first by sending out an email to the associated technical contacts detailing what software will be updated and when, followed by the installation of said software.

Full details of the process, including a calendar detailing the content publication and patching, can be found on the Linux Server Patching project website.

Preparing Your Applications For Automatic Patching¶

New servers are automatically enrolled in the automatic patching process. You can request to have your server patched either Tuesday, Wednesday, or Thursday morning. If not specified, a date will be automatically assigned based on our current load.

At a minimum, applications should meet the following criteria for best results:

1. The project must have two or more environments. Development and Production are required.

   We patch Development servers 2 weeks before we patch Production servers, which ensures time to catch and fix issues before production systems are impacted.

2. The software must be capable of automatic shutdown and startup with systemd.

3. The software must only use repositories mirrored by Satellite.

   If you have requirements not met by our existing mirrors, we are happy to add these on request.

4. Yum packages must not be locked to a specific version.

Patching for Clustered applications¶

Clustered applications will need some custom work to ensure that they are patched in a way that ensures uptime and data integrity. This ia collaborative effort.

Please open a Clustered Patching Request and we will be happy to work through the process with you.

Installing Software¶

This is a common request. While CIA Linux can handle ad-hoc requests for software installation, it is better for everyone involved if we collaborate via a GitOps workflow.

In short, this means that we create a GitLab project for your server/application that includes an Ansible playbook detailing how the server needs to be configured in order to properly run your application.

This playbook is a source of truth, documentation, and audit trail all in one. It helps to ensure that best practices are being followed, security is being maintained, and that your applications and servers are configured the same way across all environments.

What About 3rd Party Software?¶

We already mirror a significant amount of sotware in Satellite. Chances are, we already have what you are looking for, and all that is necessary will be to enable the proper yum repository.

The full list of mirrored software can be found on the Satellite GitLab Project Page.

However, if the software that you need is not present, we can mirror it for you! Just send us a request.

Containers¶

Containers are a great development tool and use is increasing significantly in ITS. Here are some guidelines to facilitate your work:

Selecting a Container Runtime¶

Pick your container platform carefully. There are 3 options when running on RHEL servers:

1. OpenShift
2. Podman
3. Red Hat's forked version of Docker (v1.13.1)
4. Docker CE or Docker EE (if you have a license)

OpenShift is the preferred container runtime platform in ITS.

Podman and Red Hat's forked version of Docker are the only two tools that will allow you to access Satellite yum repositories. Of the two, Podman is the preferred option as it is under active development, and has a full feature set, on par with modern versions of Docker.

Docker CE and Docker EE are both poor choices for working with Red Hat container images as they can not easily install packages with yum or dnf.

Server Configuration¶

If you choose to run Podman or Docker on your server, you should ensure that your /var directory is large enough to handle the number of containers you plan to manage.

You will also need to coordinate with CIA Linux to ensure that Docker can manage iptable rules.

Configuration Management¶

CIA Linux is moving towards a GitOps workflow for managing both internal applications, as well as for supporting other teams with their application and server management.

With the migration to our new Satellite server, CIA Linux will also be migrating all of our configuration management from a mix of Puppet and Ansible exclusively to Ansible.

For application administrators, we strongly recommend joining us in using git and Ansible to collaboratively describe the required state of the server that will result in your application running the way that you need.

Git¶

Git repositories, stored in GitLab projects, are the primary repository for CIA Linux programs, scripts, configuration files, and documentation.

• All appropriate content should be stored in GitLab projects under the cia group unless it is more appropriate to store them elsewhere.
• Preference is given to using Ansible as a form of executable documentation.
• Commit messages should, whenever possible, follow the Conventional Commits format. This commit message format may be optional on some projects, but will be obligatory on others. In cases where it maybe optional, it is still preferred.
• Binaries should not be included in Git repositories when it can be avoided.
• When binaries must be included, please use Git LFS.
• Commits should be scoped and the scope kept small. This makes reviewing and auditing much easier.

Versioning¶

Preference is given to using Semantic Versioning when possible.

Forked Software¶

When maintaining a fork of upstream packages (such as Ansible roles), the convention is to match the versioning convention used upstream, and to prefix the same release numbers provided upstream with mcgill- to indicate our forked version.

Whenever possible, this process should be automated to ensure that we always have access to the most up-to-date software.

Coding Standards¶

1. Always use Canadian English spelling.
2. These coding standards are version-independent and "always-current".
3. All new code should follow the current standards.
4. Existing code in older versions may be updated, but doesn't necessarily have to be. Especially for larger code-bases, updating the code of a previous version for the current standards may be too huge of a task. However, code in current versions should follow the current standards.

Indenting and Whitespace¶

• Use an indent of 2 spaces, with no tabs.
• Lines should have no trailing whitespace at the end.
• Files should be formatted with \n as the line ending (Unix line endings), not \r\n (Windows line endings).
• All text files should end in a single newline (\n). This avoids the verbose "\ No newline at end of file" patch warning and makes patches easier to read since it's clearer what is being changed when lines are added to the end of a file.

Line length and wrapping¶

• In general, all lines of code should not be longer than 80 characters.
• Lines containing longer function names, function/class definitions, variable declarations, etc are allowed to exceed 80 characters.
• Control structure conditions may exceed 80 characters, if they are simple to read and understand
• Conditions should not be wrapped into multiple lines.

Comments¶

• Use inline documentation if the code is anything more than basic. When in doubt, add a comment to explain why you are doing something, as well as what it does.
• When your coding language support automatic documentation generation (usually by parsing inline comments), conform to those standards so that the tool can be used.

Example URLs¶

Use "example.com" for all example URLs, per RFC 2606.

Naming Conventions¶

Functions and variables¶

Functions should be named using lowercase, and words should be separated with an underscore. Functions should in addition have the grouping/module name as a prefix, to avoid name collisions between modules.

Variables should be named using lowercase, and words should be separated either with uppercase characters (example: $lowerCamelCase) or with an underscore (example: $snake_case). Be consistent; do not mix camelCase and snake_case variable naming inside a file.

Persistent Variables¶

Persistent variables should be named using all lowercase letters, and words should be separated with an underscore. They should use the grouping/module name as a prefix, to avoid name collisions between modules.

File Templates¶

The template name should match the destired output filename + the template extension. If there is a risk of a file name collission, then the desired path of the file should be included, replacing slashes with underscores.

For example, in the case of Ansible's template module, the corresponding jinja2 files should be:

• sssd.conf.j2 or
• etc_sssd_sssd.conf.j2

Markdown¶

• All Markdown documents should follow the CommonMark specs.
• Exceptions can be made for GitLab Markdown particularly where the Markdown is used to refer to things in GitLab and is most likely to be rendered and viewed in GitLab (wikis, issues, MRs etc)
• Enhancements to the Markdown standard should be limited, however common enhancements include:
  • mermaid for inline diagramming. This is supported natively in GitLab Markdown, and in this MkDocs-based Handbook.
  • admonitions, which are only supported in this MkDocs-based Handbook unless otherwise specified.
• The use of HTML is permitted, but discouraged if the same results can be accomplished with generic Markdown.