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