Skip to content

Latest commit

 

History

History
177 lines (135 loc) · 6.21 KB

INSTALL.md

File metadata and controls

177 lines (135 loc) · 6.21 KB
Raw

Installing Honeydipper

Prerequisites

  • A running redis server

Step 1: Prepare your bootstrap repo

As described in the architecture/design document, Honeydipper loads configurations directly from one or many git repos. You can put the repo locally on the machine or pod where Honeydipper is running, or you can put the repos in GitHub, Bitbucket or Gitlab etc, or even mix them together. Make sure you configuration repo is private, and protected from unauthorized changes. Although, you can store all the sensitive information in encrypted form in the repo, you don't want this to become a target.

Inside your repo, you will need a init.yaml file. It is the main entrypoint that Honeydipper daemon seeks in each repo. See the Configuration Guide for detailed explanation. Below is an example of the minimum required data to get the daemon bootstrapped:

# init.yaml
---
repos:
  - repo: https://github.com/honeydipper/honeydipper-config-essentials.git

drivers:
  redisqueue:
    connection:
      Addr: <redis server IP>:<port>
      # uncomment below line if your redis server requires authentication
      # Password: xxxxxxxx
  redispubsub:
    connection:
      Addr: <redis server IP>:<port>
      # uncomment below line if your redis server requires authentication
      # Password: xxxxxxxx

Step 2: Bootstrap your daemon

Running in Kubernetes

This is the recommended way of using Honeydipper. Not only this is the easiest way to get Honeydipper started, it also enables Honeydipper to take advantage of the power of Kubernetes.

Using helm charts

To pass the information about the bootstrap config repo to Honeydipper daemon, the recommended way is to put all the information in a yaml file rather than use --values option during helm install. For example:

# values.yaml
---
daemon:
  env:
    - name: REPO
      value: [email protected]/example/honeydipper-config.git
    - name: DIPPER_SSH_KEY
      valueFrom:
        secretKeyRef:
          name: example-secret
          key: id_rsa

Note that, we need to provide a ssh key for Honeydipper daemon to be able to fetch the private repo using ssh protocol. Make sure that the key exists in your cluster as a secret.

Once the values file is prepared, you can run the helm install command like below.

helm install --values values.yaml orchestrator incubator/honeydipper

If you want to use an older version of the chart, (as of now, the latest one is 0.1.3), use --version to specify the chart version. By default, the chart uses the latest stable version of the Honeydipper daemon docker image, (latest is 1.0.0 as of now). You can change the version by specifying --set daemon.image.tag=x.x.x in your helm install command.

Currently, the chart is available from incubator repo, and the honeydipper repo from helm hub as well. You may also choose to customize and build the chart by yourself following below steps.

git clone [email protected]:honeydipper/honeydipper-charts.git
cd honeydipper
helm package honeydipper

You should see the chart file honeydipper-x.y.z.tgz in your current directory.

Create your own manifest file

You can use the below manifest file as a template to create your own. Note that, the basic information needed, besides the docker image for Honeydipper daemon, is the same, REPO and DIPPER_SSH_KEY.

---
apiVersion: apps/v1beta2
kind: Deployment
metadata:
  name: honeydipper-daemon
  labels:
    app: honeydipper-daemon
spec:
  template:
    metadata:
      name: honeydipper-daemon
    spec:
      containers:
        - name: honeydipper-daemon
          image: honeydipper/honeydipper:1.0.0
          imagePullPolicy: Always
          env:
            - name: REPO
              value: [email protected]/example/honeydipper-config.git
            - name: DIPPER_SSH_KEY
              valueFrom:
                secretKeyRef:
                  namne: example-secret
                  key: id_rsa

For the webhook driver, you will need to create a service.

apiVersion: v1
kind: Service
metadata:
  name: honeydipper-webhook
spec:
  type: LoadBalancer
  ports:
  - name: webhook
    targetPort: 8080
    port: 8080
selector:
    app: honeydipper-daemon

Running as docker container

docker run -it -e '[email protected]/example/honeydipper-config.git' -e "DIPPER_SSH_KEY=$(cat ~/.ssh/id_rsa)"  honeydipper/honeydipper:1.0.0

Replace the repo url with your own, and specify the private key path for accessing the private repo remotely. You may replace the value of DIPPER_SSH_KEY with a deploy key for your config repo.

Building from source

Prerequisites:

  • Golang >= 1.11.xx
  • Git
  • Instructions assume POSIX compliant shell

Instructions

export GO111MODULE=on
git clone https://github.com/honeydipper/honeydipper.git
pushd honeydipper
go install -v ./...
popd
[email protected]/example/honeydipper-config.git DIPPER_SSH_KEY="$(cat ~/.ssh/id_rsa)" honeydipper

NOTE: Specifying GO111MODULE is not necessary in golang >= 1.13.x

You don't have to specify DIPPER_SSH_KEY if the key is used by your ssh client by default.

Alternatively, you can follow the developer setup guide the download and build.

Step 3: Hacking away

That's it — your Honeydipper daemon is bootstrapped. You can start to configure it to suit your needs. The daemon pulls your config repos every minute, and will reload when changes are detected. See the Honeydipper Guides for more documents, including a way to setup GitHub push event-driven reload.