• This repository has been archived on 24/Mar/2023
  • Stars
    star
    638
  • Rank 70,537 (Top 2 %)
  • Language
    Go
  • License
    Apache License 2.0
  • Created over 6 years ago
  • Updated over 1 year ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

A better way to deploy Kubernetes Helm charts

Replicated Ship has been superseded by Kots.

Kots provides the core functionality of Ship, but with a different architecture. While Ship will continue to be supported, it is no longer under active development.

Replicated Ship

Test Coverage Maintainability CircleCI Docker Image Go Report Card GitHub stars

Replicated Ship is a Kubernetes app deployment and automation tool that can:

  1. Track and automate the maintenance of 3rd-party applications whether packaged as Helm Charts, Kubernetes YAML manifests, or Knative apps.
  2. Quickly develop app kustomizations using Ship's easy-to-use import & migration tools.
  3. Enable application developers to package and deliver a canonical version of their application configuration while encouraging last-mile customizations through overlays instead of forking or upstream requests.

Read on for more details on Ship features and objectives, or skip ahead to getting started.

Track and automate the maintenance of 3rd-party applications

Ship enables cluster operators to automatically stay in sync with upstream changes while preserving their custom configurations and extensions (adds, deletes and edits) without git merge conflicts. This is possible because of how the three operating modes of Ship invoke, store and apply Kustomizations, a type of Kubernetes specific patch, produced by a cluster operator.

Customizing Helm Charts, Kube YAML and Knative with Kustomize

Ship exposes the power of Kustomize as an advanced custom configuration management tool for Helm charts, Kubernetes manifests and Knative applications. The easy-to-use UI of Ship (launched via ship init) calculates the minimal patch YAML required to build an overlay and previews the diff that will be the result of applying the drafted overlay. gif of calculation

Additionally, the unfork command can migrate forked manifests and environment versions to Kustomize.

The output of the init and unfork modes will result in the creation of a directory that includes the finalized overlay YAML files, a kustomization.yaml and a Ship state.json.

Enable app developers to allow for last-mile configuration

Configuration workflow ship.yaml files can be included in Kubernetes manifest or Helm chart repos, to customize the initial ship init experience. See Customizing the Configuration Experience for more details or check out the examples in the github.com/shipapps org.

Getting Started

Installation

Ship is packaged as a single binary, and Linux and MacOS versions are distributed:

  • To download the latest Linux build, run:
curl -sSL https://github.com/replicatedhq/ship/releases/download/v0.51.2/ship_0.51.2_linux_amd64.tar.gz | tar zxv && sudo mv ship /usr/local/bin
  • To download the latest MacOS build, you can either run:
curl -sSL https://github.com/replicatedhq/ship/releases/download/v0.51.2/ship_0.51.2_darwin_amd64.tar.gz | tar zxv && sudo mv ship /usr/local/bin
brew install ship
  • To download the latest Windows build, grab the tar.gz from the releases page.

Alternately, you can run Ship in Docker, in which case you can pull the latest ship image with:

docker pull replicated/ship

Initializing

After Ship is installed, create a directory for the application you'll be managing with Ship, and launch Ship from there, specifying an upstream Helm chart or Kubernetes yaml:

mkdir -p ~/my-ship/example
cd ~/my-ship/example
ship init <path-to-chart> # github.com/helm/charts/tree/master/stable/grafana

Alternately, the same command run through Docker:

mkdir -p ~/my-ship/example
cd ~/my-ship/example
docker run -p 8800:8800 -v "$PWD":/wd -w /wd \
    replicated/ship init <path-to-chart> # github.com/helm/charts/tree/master/stable/grafana

Note: you may need to point your browser to http://127.0.0.1:8800 if ship's suggested localhost URL doesn't resolve.

You'll be prompted to open a browser and walk through the steps to configure site-specific values for your installation, updating Helm values (if it's a chart), and making direct edits to the Kubernetes yaml (or Helm-generated yaml), which will be converted to patches to apply via Kustomize.

After completing the guided 'ship init' workflow, you'll see that Ship has generated several directories and files within the current working directory.

β”œβ”€β”€ .ship
β”‚   └── state.json
β”œβ”€β”€ base
β”‚   β”œβ”€β”€ clusterrole.yaml
β”‚   β”œβ”€β”€ ...
β”‚   └── serviceaccount.yaml
β”œβ”€β”€ overlays
β”‚   └── ship
β”‚       └── kustomization.yaml
└── rendered.yaml

.ship/state.json - maintains all the configuration decisions made within the ship init flow, including the path to the upstream, the upstream's original values.yaml, any modifications made to values.yaml, and any patch directives configured in the Kustomize phase.

The base/ and overlays/ folders contain the various files that drive the Kustomization process.

The rendered.yaml file is the final output, suitable to deploy to your Kubernetes cluster via

kubectl apply -f rendered.yaml

If you need to revise any of the configuration details, you can re-invoke ship init <path-to-chart> to start fresh, or ship update --headed to walk through the configuration steps again, starting with your previously entered values & patches as a baseline.

Three operating modes

Replicated Ship Modes

ship init

Prepares a new application for deployment. Use for:

  • Specifying the upstream source for an application to be managed -- typically a repo with raw Kubernetes yaml or a Helm chart
  • Creating and managing Kustomize overlays to be applied before deployment
  • Generating initial config (state.json) for the application, and persisting that config to disk for use with the other modes

ship watch

Polls an upstream source, blocking until any change has been published. Use for:

  • Triggering creation of pull requests in a CI pipeline, so that third party updates can be manually reviewed, and then automatically deployed once merged

ship update

Updates an existing application by merging the latest release with the local state and overlays. Use for:

  • Preparing an update to be deployed to a third party application
  • Automating the update process to start from a continuous integration (CI) service

Unforking

Another initialization option is to start with a Helm chart or Kubernetes manifest that has been forked from an upstream source, and to "unfork" it.

ship unfork <path-to-forked> --upstream <path-to-upstream>

or

docker run -v "$PWD":/wd -w /wd \
    replicated/ship unfork <path-to-forked> \
    --upstream <path-to-upstream>

With this workflow, Ship will attempt to move the changes that prompted the fork into 'overlays' that can be applied as patches onto the unmodified upstream base. You can inspect the rendered.yaml to verify the final output, or run through ship update --headed to review the generated overlays in the Ship admin console.

CI/CD Integration

Once you've prepared an application using ship init, a simple starting CI/CD workflow could be:

ship watch && ship update

or

docker run -v "$PWD":/wd -w /wd replicated/ship watch && \
    docker run -v "$PWD":/wd -w /wd replicated/ship update

The watch command is a trigger for CI/CD processes, watching the upstream application for changes. Running ship watch will load the local state file (which includes a content hash of the most recently used upstream) and periodically poll the upstream application and exit when it finds a change. ship update will regenerate the deployable application assets, using the most recent upstream version of the application, and any local configuration from state.json. The new rendered.yaml output can be deployed directly to the cluster, or submitted as a pull request into a GitOps repo.

With chart repo you have commit privileges on, you, you can see this flow in action by running ship init <path-to-chart> and going through the workflow, then ship watch --interval 10s && ship update to start polling, then commit a change to the upstream chart and see the ship watch process exit, with rendered.yaml updated to reflect the change.

Customizing the Configuration Experience

Maintainers of OTS (Off the Shelf) software can customize the ship init experience by including a ship.yaml manifest alongside a Helm Chart or Kubernetes manifest. The Replicated Ship YAML format allows further customization of the installation process, including infrastructure automation steps to spin up and configure clusters to deploy to. (If you're wondering about some of the more obscure Ship CLI option flags, these mostly apply to ship.yaml features)

Ship Cloud

For those not interested in operating and maintaining a fleet of Ship instances, Ship Cloud is available as a hosted solution for free. With Ship Cloud, teams can collaborate and manage multiple OTS Kubernetes application settings in one place, with Ship watching and updating on any upstream or local configuration changes, and creating Pull Requests and other integrations into CI/CD systems.

Contributions and Local Development

For instructions for building the project and making contributions, see Contributing.

Community

For questions about using Ship, there's a Replicated Community forum, and a #kots channel in Kubernetes Slack.

For bug reports, please open an issue in this repo.

More Repositories

1

dockerfilelint

An opinionated Dockerfile linter.
JavaScript
990
star
2

kots

KOTS provides the framework, tools and integrations that enable the delivery and management of 3rd-party Kubernetes applications, a.k.a. Kubernetes Off-The-Shelf (KOTS) Software.
Go
888
star
3

kURL

Production-grade, airgapped Kubernetes installer combining upstream k8s with overlays and popular components
Shell
737
star
4

troubleshoot

Preflight Checks and Support Bundles Framework for Kubernetes Applications
Go
533
star
5

ttl.sh

An anonymous & ephemeral Docker image registry
TypeScript
461
star
6

outdated

Kubectl plugin to find and report outdated images running in a Kubernetes cluster
Go
422
star
7

kotsadm

Kotsadm has been merged into the KOTS repo
JavaScript
250
star
8

unfork

Kubectl plugin to find forked Helm Charts and other K8s resources and unfork them with Kustomize
Go
145
star
9

gatekeeper

Kubernetes Operator to manage Dynamic Admission Controllers using Open Policy Agent
Go
107
star
10

krew-plugin-template

GitHub Repository Template for creating new Kubectl plugins
Go
65
star
11

kubeflare

A Kubernetes Operator to manage Cloudflare settings via a declarative Kubernetes API
Go
56
star
12

pvmigrate

Go
54
star
13

hugo-algolia

Enables search with Algolia in Hugo static sites
JavaScript
47
star
14

sbctl

Go
40
star
15

replicated

A CLI to create, edit and promote releases in Replicated
Go
34
star
16

local-volume-provider

A Velero plugin for backup/restore directly to Kubernetes volumes.
Go
32
star
17

troubleshoot.sh

JavaScript
29
star
18

fromlatest.io

JavaScript
19
star
19

embedded-cluster

Go
18
star
20

replicated-field-labs

Defines the Replicated Platform Hands-On Labs powered by the Instruqt platform
Shell
16
star
21

studio

Streamline your Replicated Application development in 3 easy steps, or your money back!
TypeScript
14
star
22

kots-sentry

Makefile
14
star
23

kurl.sh

JavaScript
11
star
24

libyaml

Go
11
star
25

replicated-lint

YAML linting tools for Replicated applications
TypeScript
8
star
26

ekco

ekco: Embedded kURL Cluster Operator
Go
8
star
27

replicated-docs

Replicated Product Documentation
JavaScript
8
star
28

replicated-starter-ship

Starter repo for managing Ship Apps in GitHub
Makefile
8
star
29

k8s-secret-generator

Go
7
star
30

enterprise-gtm-starter

Go-to-market starter project for Replicated apps
Go
7
star
31

ips

Current list of Replicated public facing IP addresses
6
star
32

replicated-actions

TypeScript
6
star
33

kots-lint

Lint a KOTS application before deploying it
Go
6
star
34

kubectl-traceroute

A kubectl plugin to diagnose and debug why a service is not responding
Go
6
star
35

homebrew-ship

Homebrew Formulae to ship binaries, powered by @replicatedhq
Ruby
6
star
36

kots.io

Docs site for KOTS
SCSS
6
star
37

vendor-docs-starter

6
star
38

help-center

Replicated help center
HTML
4
star
39

replicated-sdk

Service that allows you to embed key Replicated features alongside your application.
Go
4
star
40

ansible

Shell
4
star
41

helm-charts

Smarty
4
star
42

replicated-installer

Shell
4
star
43

troubleshoot-specs

Python
4
star
44

replicated-ci-demo

Example repo showcasing how to use the Replicated APIs and tools to manage your Replicated application YAML using git
Makefile
3
star
45

repl-yaml-samples

Resource for Replicated sample YAML's and snippets
3
star
46

replicated-automation

Shell
3
star
47

replicated-starter-helm

3
star
48

kots-helm

Smarty
3
star
49

platform-examples

Large and small examples of Replicated Platform capabilities
Smarty
3
star
50

kotsapps

Mustache
3
star
51

ledismock

Go
3
star
52

cc-qa-automation

Coding Challenge: QA Automation Engineer
Go
3
star
53

replicated-starter-kubernetes

Starter repo for developing Kubernetes applications on Replicated
Makefile
3
star
54

docs

Replicated Documentation
CSS
3
star
55

terraform-kots-eks

HCL
3
star
56

kots-cicd-demo

3
star
57

action-kots-lint

Dockerfile
2
star
58

exfilter

C
2
star
59

replicated-preview

CoffeeScript
2
star
60

homebrew-replicated

Replicated Homebrew Tap
Ruby
2
star
61

kots-default-yaml

YAML files used for new KOTS projects
2
star
62

kgrid

Go
2
star
63

kubectl-grid

Go
2
star
64

replicated-starter-swarm

Starter repo for developing Docker Swarm applications on Replicated
Makefile
2
star
65

kurlkinds

Host of kurl's Kubernetes clients and types.
Go
2
star
66

terraform-provider-replicated

Go
2
star
67

codeclimate-dockerfile

A CodeClimate engine for Dockerfilelint
JavaScript
2
star
68

action-k3s

JavaScript
2
star
69

tslint-config-replicated

TypeScript
1
star
70

replicated-action

A GitHub Action to interact with the Replicated API
Dockerfile
1
star
71

action-kots-release

Dockerfile
1
star
72

crd-to-openapischema

Go
1
star
73

grafana-kube-demo

Makefile
1
star
74

action-okteto-test

JavaScript
1
star
75

community

1
star
76

troubleshoot-preview

Go
1
star
77

superbigtool-k8s

1
star
78

velero-exec-hooks-qa

Shell
1
star
79

kURL-testgrid

Testgrid is a an automation testing platform for kURL
Go
1
star
80

kots-idp-example-app

Go
1
star
81

replicated-scripts

Python
1
star
82

vendor-schemas

1
star
83

license-create-download-worker

TypeScript
1
star
84

kustomize-demo

JavaScript
1
star
85

embedded-cluster-operator

Go
1
star
86

terraform-provider-kURL

this repo will be used as terraform provisioning a customer kurl cluster based on their kurl installer config
HCL
1
star
87

kots2helm

Go
1
star
88

ship-starter-compose

Starter repo for developing Docker Compose / Swarm application on Ship
Makefile
1
star
89

dehydrated-docker

Makefile
1
star