github.com/replicatedcom/ship@v0.50.0/README.md (about) 1 Replicated Ship 2 ======= 3 4 [](https://codeclimate.com/github/replicatedhq/ship/test_coverage) 5 [](https://codeclimate.com/github/replicatedhq/ship/maintainability) 6 [](https://circleci.com/gh/replicatedhq/ship) 7 [](https://microbadger.com/images/replicated/ship) 8 [](https://goreportcard.com/report/github.com/replicatedhq/ship) 9 [](https://github.com/replicatedhq/ship/stargazers) 10 11 Replicated Ship is a Kubernetes app deployment and automation tool that can: 12 13 1. Track and automate the maintenance of 3rd-party applications whether packaged as Helm Charts, Kubernetes YAML manifests, or Knative apps. 14 1. Quickly develop app [kustomizations](https://www.kustomize.io) using Ship's easy-to-use import & migration tools. 15 1. 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. 16 17 Read on for more details on Ship features and objectives, or skip ahead to [getting started](#getting-started). 18 19 ## Track and automate the maintenance of 3rd-party applications 20 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](#three-operating-modes) of Ship invoke, store and apply Kustomizations, a type of Kubernetes specific patch, produced by a cluster operator. 21 22 ## Customizing Helm Charts, Kube YAML and Knative with Kustomize 23 Ship exposes the power of Kustomize as an advanced custom configuration management tool for [Helm charts](https://www.github.com/helm/charts), Kubernetes manifests and [Knative](https://github.com/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. 24  25 26 Additionally, the `unfork` command can [migrate forked manifests](#unforking) and environment versions to Kustomize. 27 28 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. 29 30 31 ## Enable app developers to allow for last-mile configuration 32 Configuration workflow `ship.yaml` files can be included in Kubernetes manifest or [Helm](https://helm.sh/) chart repos, to customize the initial `ship init` experience. See [Customizing the Configuration Experience](#customizing-the-configuration-experience) for more details or check out the examples in the [github.com/shipapps](https://github.com/shipapps) org. 33 34 35 # Getting Started 36 37 ## Installation 38 39 Ship is packaged as a single binary, and Linux and MacOS versions are distributed: 40 - To download the latest Linux build, run: 41 ```shell 42 curl -sSL https://github.com/replicatedhq/ship/releases/download/v0.47.2/ship_0.47.2_linux_amd64.tar.gz | tar zxv && sudo mv ship /usr/local/bin 43 ``` 44 45 - To download the latest MacOS build, you can either run: 46 ```shell 47 curl -sSL https://github.com/replicatedhq/ship/releases/download/v0.47.2/ship_0.47.2_darwin_amd64.tar.gz | tar zxv && sudo mv ship /usr/local/bin 48 ``` 49 50 - ... or you can install with [Homebrew](https://brew.sh/): 51 ```shell 52 brew install ship 53 ``` 54 55 - To download the latest Windows build, grab the tar.gz from the [releases page](https://github.com/replicatedhq/ship/releases). 56 57 Alternately, you can run Ship in Docker, in which case you can pull the latest ship image with: 58 ```shell 59 docker pull replicated/ship 60 ``` 61 62 63 ## Initializing 64 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: 65 66 ```shell 67 mkdir -p ~/my-ship/example 68 cd ~/my-ship/example 69 ship init <path-to-chart> # github.com/helm/charts/tree/master/stable/grafana 70 ``` 71 72 Alternately, the same command run through Docker: 73 ```shell 74 mkdir -p ~/my-ship/example 75 cd ~/my-ship/example 76 docker run -p 8800:8800 -v "$PWD":/wd -w /wd \ 77 replicated/ship init <path-to-chart> # github.com/helm/charts/tree/master/stable/grafana 78 ``` 79 _Note: you may need to point your browser to http://127.0.0.1:8800 if ship's suggested localhost URL doesn't resolve._ 80 81 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. 82 83 After completing the guided 'ship init' workflow, you'll see that Ship has generated several directories and files within the current working directory. 84 85 ``` 86 ├── .ship 87 │ └── state.json 88 ├── base 89 │ ├── clusterrole.yaml 90 │ ├── ... 91 │ └── serviceaccount.yaml 92 ├── overlays 93 │ └── ship 94 │ └── kustomization.yaml 95 └── rendered.yaml 96 ``` 97 98 `.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. 99 100 The `base/` and `overlays/` folders contain the various files that drive the Kustomization process. 101 102 The `rendered.yaml` file is the final output, suitable to deploy to your Kubernetes cluster via 103 104 ```shell 105 kubectl apply -f rendered.yaml 106 ``` 107 108 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. 109 110 # Three operating modes 111 112  113 114 ## ship init 115 Prepares a new application for deployment. Use for: 116 - Specifying the upstream source for an application to be managed -- typically a repo with raw Kubernetes yaml or a Helm chart 117 - Creating and managing [Kustomize](https://kustomize.io/) overlays to be applied before deployment 118 - Generating initial config (state.json) for the application, and persisting that config to disk for use with the other modes 119 120 ## ship watch 121 Polls an upstream source, blocking until any change has been published. Use for: 122 - Triggering creation of pull requests in a CI pipeline, so that third party updates can be manually reviewed, and then automatically deployed once merged 123 124 ## ship update 125 Updates an existing application by merging the latest release with the local state and overlays. Use for: 126 - Preparing an update to be deployed to a third party application 127 - Automating the update process to start from a continuous integration (CI) service 128 129 ## Unforking 130 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. 131 132 ```shell 133 ship unfork <path-to-forked> --upstream <path-to-upstream> 134 ``` 135 or 136 137 ```shell 138 docker run -v "$PWD":/wd -w /wd \ 139 replicated/ship unfork <path-to-forked> \ 140 --upstream <path-to-upstream> 141 ``` 142 143 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. 144 145 146 # CI/CD Integration 147 Once you've prepared an application using `ship init`, a simple starting CI/CD workflow could be: 148 149 ```shell 150 ship watch && ship update 151 ``` 152 153 or 154 ```shell 155 docker run -v "$PWD":/wd -w /wd replicated/ship watch && \ 156 docker run -v "$PWD":/wd -w /wd replicated/ship update 157 ``` 158 159 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](https://www.weave.works/blog/what-is-gitops-really) repo. 160 161 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. 162 163 # Customizing the Configuration Experience 164 165 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](https://help.replicated.com/docs/ship/getting-started/yaml-overview/) 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) 166 167 # Ship Cloud 168 169 For those not interested in operating and maintaining a fleet of Ship instances, [Ship Cloud](https://www.replicated.com/ship) 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. 170 171 # Contributions and Local Development 172 173 For instructions for building the project and making contributions, see [Contributing](./CONTRIBUTING.md). 174 175 # Community 176 177 For questions about using Ship, there's a [Replicated Community](https://help.replicated.com/community) forum, and a [#ship channel in Kubernetes Slack](https://kubernetes.slack.com/channels/ship). 178 179 For bug reports, please [open an issue](https://github.com/replicatedhq/ship/issues/new) in this repo.