Reference Implementation

Introduction

A reference implementation is an open-source, fully functional example of a system designed to mirror a closed-source setup in a government domain or data center. It enables local deployment on a developer’s machine, facilitating rapid prototyping, testing, and development in realistic environments. This concept provides a practical, reusable blueprint that demonstrates how to deploy and manage complex systems. It ensures alignment with production-like conditions while promoting openness and collaboration.

In the C2 Platform, a reference implementation leverages an Ansible mirror inventory project to create an automated, open-source replica of closed-source environments. It is a core part of the development environment, where it is used to develop automation in the form of Ansible content. It fully automates setup and provisioning using IaC principles like GitOps and desired state configuration. This setup empowers Ansible engineers to build and test systems locally, aligning with the open, unless principle. It boosts productivity, collaboration, and reuse by offering adaptable examples for customer domains. Ansible drives this automation, replicating target architectures while embedding best practices for scalability, security, and maintainability— providing a solid foundation for real-world adaptations. It also incorporates Ansible content, such as Ansible collections and Ansible roles, to ensure modular and reusable automation.

Key Components

A reference implementation in the C2 Platform is a replica of a closed-source system running locally. It is created using the development environment and an Ansible mirror inventory project. The Ansible mirror inventory project mirrors the inventory in the customer domain and contains the complete desired state for the replica system.

The integration of Vagrant and Ansible forms a complete solution. Vagrant sets up the virtual infrastructure, while Ansible installs and manages software on the nodes. For instance, in the GIS Platform example, this includes deploying ArcGIS Enterprise Web Adaptor, Portal, Server, Datastore, FME, and more. This modular design ensures that the reference implementation can be easily extended or modified to suit specific needs, while maintaining fidelity to the mirrored production environment.

For more information, see these resources:

• Development Environment: A local open-source development environment boosts Ansible automation by providing maximum flexibility and productivity for rapid iteration, testing, and independence from external infrastructure teams or even other engineers on your team due to shared environments.
• Ansible Mirror Inventory Project: Explore the integration of Ansible and Vagrant in a reference implementation project, pivotal to developing and mimicking real-world infrastructure locally within the C2 framework.

How It Works

As illustrated in the diagram below, the reference implementation involves collaboration between an Ansible engineer (on the left) and an Ansible operator (on the right).

Role of the Ansible Engineer

The Ansible engineer maintains an open-source Ansible mirror inventory project that mirrors a closed-source Ansible inventory project at RWS. They use this mirror to provision a replica system locally, leveraging Ansible combined with Vagrant in the development environment. The engineer also develops Ansible content, such as Ansible collections and Ansible roles, which they publish to Ansible Galaxy for sharing.

Role of the Ansible Operator

On the other side, the Ansible operator manages the desired state in the closed-source Ansible inventory project and specifies what Ansible content (collections and versions) is to be used. Ansible handles the downloading of Ansible content from Ansible Galaxy.¹

The operator uses this Ansible inventory project to lifecycle manage (LCM) and maintain the actual GIS Platform system in the customer domain. The operator deploys and manages GIS Platform services using Ansible.

Using the Mirror as a Reference

The Ansible operator uses the Ansible mirror inventory project as a reference, benefiting from its proven code, patterns, solutions, and recipes. It provides a working example of how Ansible content is configured or can be used. Operators can also refer to this website’s accompanying documentation, which explains how to utilize the example. For an example of such documentation, see:

• Verify Environment Group Check: Verify and review the implementation of an environment check to ensure nodes are in exactly one environment group.

Ansible Engineering in Customer Domains

Typically, Ansible engineering of Ansible content can also occur inside the customer domain, as was the case for the RWS project. However, this is not depicted in the diagram because the RWS domain has only a pseudo development environment. Ideally, most Ansible engineering work will be done in the C2 Platform domain. This typically includes developing Ansible content and always includes desired state configuration in the Ansible mirror inventory project. The mirror functions as an example that can be copied as a whole or in part into the customer domain’s Ansible inventory project. If Ansible content is developed, the Ansible operator will configure (also in the Ansible inventory project) the Ansible content (collections and versions) that Ansible should use.

Core Attributes

Here are the main features of a reference implementation:

• Comprehensive Implementation: Covers all configurations, settings, and interdependencies for seamless operation, fully mirroring the intended system. This includes detailed handling of dependencies, networking, and data flows to ensure operational parity.
• Parity with Production: For example, the GIS Platform reference implementation closely emulates the setup at Rijkswaterstaat (RWS), aligning with real-world environments while adapting to local constraints.
• Detailed Documentation and Best Practices: Includes extensive Ansible documentation explaining purpose, configurations, best practices, and management. This serves as a key resource for teams, with examples of usage and troubleshooting tips.
• Training and Consistency: Acts as a tool for training, helping teams learn efficient deployment and management. It also ensures consistency in infrastructure, reducing errors through standardized patterns.

In the context of Ansible and Vagrant, it includes all components of an Ansible inventory project for configuration, along with a Vagrantfile for VM setup. These elements are well-documented and tested to accurately represent the target system, facilitating iterative improvements and community contributions.

Purpose and Benefits

A reference implementation provides a fully functional replica of a production system, ensuring efficient and consistent infrastructure management while closely aligning with real-world deployments. This is essential for complex projects, such as the GIS Platform at Rijkswaterstaat (RWS), where accuracy and reliability are critical. It bridges the gap between development and production by offering a testable, modifiable base that reduces deployment risks.

It demonstrates practical software usage and configuration, offering a flexible starting point for customization. By leveraging open-source components like Ansible collections, organizations can build on shared work, accelerating development, ensuring uniform deployments, and fostering collaboration. This approach minimizes rework and enhances knowledge transfer across teams.

Vagrant is not used in government domains or data centers, though it could potentially be adapted due to its support for VMware provisioners, which are commonly employed there. Government domains do include a development environment, but it is often a suboptimal variant referred to as a pseudo development environment due to constraints like security and resource limitations.

Additional Information

For further reference, explore the following information:

• Development Environment: A local open-source development environment boosts Ansible automation by providing maximum flexibility and productivity for rapid iteration, testing, and independence from external infrastructure teams or even other engineers on your team due to shared environments.
• Ansible Mirror Inventory Project: Explore the integration of Ansible and Vagrant in a reference implementation project, pivotal to developing and mimicking real-world infrastructure locally within the C2 framework.
• Ansible Inventory Project: A structured collection of files used for managing hosts and configurations. It typically includes inventory files, playbooks, host configurations, group variables, and Ansible vault files.