A Model for Adopting Replicated

This article is designed to help guide you through implementing Replicated features into your application and more broadly into your organization. This includes recommendations for integration into your continuous integration environments, deployment manifests, and Vendor Portal and even further into things like how best to integrate your support process with ours and how to use the cloud native functionality that using Replicated brings to help you sell your own software.

As you go through this architecture we will include design decisions that were used to help you understand why a particular decision was made. You can use this knowledge to also help you understand when your particular situation means a different decision is advantageous. This architecture is meant to give you a path to success and not constrain your available options.

Architecture Overview

The way you build, release, and deploy your software is important to the success of running your commercial application in a customer-provided cloud-native environment. In this section, we explore the various components and decisions to best support deploying into those customer provided environments. We will cover the components of this architecture in more detail in the sections below.

architecture overview

Application Architecture

Your software architecture is an important consideration as part of making your application ready to run in customer provided environments. In general, following the design considerations outlined in the 12 Factor App will help you build applications that are resilient to failure and scale well in any cloud-native environment, on-prem or otherwise.

application architecture

Consider the following design decisions when building your application:

Decision ID Design Decision Justification Implication
APP-001 Avoid using cloud-proprietary services Cloud proprietary services can lock your customers into a specific cloud and limit your future options Increased cloud independence and lower support burden
APP-002 Use horizontally scalable services Horizontally scalable services allow customers to scale as necessary to support increased demand May limit some of your service options
APP-003 Use declaratively database schemas (see schemahero.io) Allows seamless life cycle management of your application None
APP-004 Wait for resources to become available Avoids exposing crashloop backoff conditions to end users provides expected end user behavior, same outcome can be achieved in packaging with init containers if necessary

Build Architecture

The most frequent intersection between Replicated and your own organization will be through the build process. We recommend that for every commit that passes your code quality checks, that you update container images you and promote the release to your unstable release channel. We also recommend signing your commits and container images to help validate the security of your supply chain.

build architecture
Decision ID Design Decision Justification Implication
BUILD-001 Integrate the Replicated cli with your CI workflow Integration with your CI pipeline ensures that every iteration of your software is available for testing and can be promoted quickly to customers None
BUILD-002 Use the --auto flag on the replicated release create command This flag embeds best practices for creating replicated releases The functionality of the auto flag may change as new best practices are implemented and release notes should be watched for change in behavior
BUILD-003 Sign all commits Signing commits helps show you are conforming to a secure supply chain None
BUILD-004 Sign container images and provide verification mechanism Signing container images helps show you are conforming to a secure supply chain None

Package Architecture

Packaging your application is a core part of its delivery to customers. We recommend that you simplify your packaging by following some standards such as aligning the branch name of your package repository to the branch names of your release channel. Additionally, we recommend that you package your application as a helm chart so that you can allow customers the flexibility of installing via helm directly or via the application console.

package architecture

When packaging your software we recommend you follow the design considerations below:

Decision ID Design Decision Justification Implication
PACK-001 Use a git branch per channel for your deployment repository that match the release channel in the vendor portal This idiom lets you quickly identify which section of your source aligns to what release channel. It also follows the in-built --auto flags of the replicated CLI None
PACK-002 Have preflight checks for any underlying constraints you have on the underlying kubernetes cluster Preflight checks can guarantee your underlying platform meets your expectations Missing preflight checks can result in later support calls when the application does not perform as expected
PACK-003 Use Helm charts to create your application manifests Helm charts open up additional deployment options and allow you to build on other charts While Helm charts open additional deployment options, they introduce additional complexity. Caution should be taken to keep the go templates as simple as possible. Additionally, manifests that are go templates are not parseable yaml which can limit options for linting and other automated manifest manipulation.
PACK-004 Do not package an ingress controller Ingress should be provided by the distribution Not providing an ingress controller means you must limit some of the ingress features you can use. A preflight check can be used to verify a compatible controller is being used.

Release Architecture

When a revision of your software has been tested and is ready to be released, we recommend that you use the package repository to communicate the changes they can expect in a release.

release architecture

 When releasing your software we recommend you follow the design considerations below:

Decision ID Design Decision Justification Implication
RELE-001 For customer facing channels use semantic versioning Semver will allow your customers to understand the expected impact of upgrading Using semver requires diligences to maintain the expected contract with your customers
RELE-002 Match release channels and package repository branch names Simplifies logic between systems None
RELE-003 Be consistent in your versioning across channels Consistent versioning will help if you want to switch a customer between channels None

Customer Delivery Architecture

Customer Delivery is the final customer initiated action that will result in your application being installed into their environment. For first time deployments, We recommend that you provide a clear and concise installation guide that will help your customers get started with your application. We also recommend that you provide a clear and concise upgrade guide that will help your customers upgrade to new versions of your application. You can use our documentation templates mentioned in the documentation architecture section to help you get started.

customer delivery architecture


For customer deployments we recommend you follow the design considerations below:

Decision ID Design Decision Justification Implication
DELV-001 For each customer, guide them to use whichever cluster deployment model (existing vs embedded) they are already the most familiar or comfortable with. All clusters can be run well, but not all customers can run all clusters. By meeting your customers where they are, you optimize their chance of success. Replicated enables you to deploy anywhere, the most important thing to consider is what is best for that customer.
DELV-002 Enterprise customer should integrate with existing observability and logging platforms Integrating with their existing stacks means the customer will be able to effectively manage the availability and performance of the installation Providing procedures and documentation to help customers integrate with their existing log and monitoring platforms will help keep your software available and reduce MTTR when there is an issue.

Support Architecture

By integrating the replicated platform into your support processes you can gain significant improvements by reducing total cases and time to resolution. To best leverage these features be sure to integrate the support bundles and support bundle analyzers into your support or incident process.

support architecture
Decision ID Design Decision Justification Implication
SUPP-001 Integrate support bundles with your incident process Support bundles help support teams rapid pinpoint the cause of incidents Reduced time to resolve
SUPP-002 After each incident write an analyzer that would detect the issue in the future Analyzers help the customer to self troubleshoot and remediate and increase confidence in the product Less support cases & faster resolution of those opened
SUPP-003 At your initial deployment, add support analyzers for your known log files and issues Analyzers help the customer to self troubleshoot and remediate and increase confidence in the product Less support cases & faster resolution of those opened
SUPP-004 Create status informers for all your long running statefulsets and deployments Status informers will allow the admin console to accurately depict the status of your application Less support cases & accurate representation of state and telemetry

Documentation Architecture

Documentation is an important part of all software. By using replicated, you can integrate our documentation into your existing documentation framework.

documentation architecture
Decision ID Design Decision Justification Implication
DOCS-001 Integrate the Enterprise section of docs into your own documentation Replicated provided documentation reduces burden on your technical writing staff None
DOCS-002 Watch the replicated-docs repository for changes and update your docs accordingly Up to date docs help you and your customers install and support efficiently None
DOCS-003 Use vendor doc templates Up to date docs help you and your customers install and support efficiently None

Sales Architecture

By using Replicated, you gain access to a host of features for your application that help you sell more and run proof-of-concepts (POCs) better.

sales architecture
Decision ID Design Decision Justification Implication
SELL-001 Integrate replicated sales collateral into your own Replicated collateral helps articulate the value the Replicated platform brings to your customers Enhanced sales
SELL-002 Integrate replicated license management with your SFDC (Salesforce Datacenter) This gives you a single source of truth in the existing system you have Customer clarity and simplified operations


This model has a worksheet with each of the decisions in a tabular format. You can copy this worksheet and for each decision here track if you are following the model or provide architectural notes on why a different decision was reached.