Skip to content

H
helm3
Commit fb94165b authored by jackgr's avatar jackgr
Browse files
Options

Rename client to dm, update README.md and fix more minor issues.

parent 9e75c924
Show whitespace changes
Inline Side-by-side
Showing with 212 additions and 133 deletions
Makefile
View file @ fb94165b
...@@ -4,10 +4,14 @@ TARGETS := all build test push container clean ...@@ -4,10 +4,14 @@ TARGETS := all build test push container clean
SUBDIRS_TARGETS := \ SUBDIRS_TARGETS := \
$(foreach t,$(TARGETS),$(addsuffix $t,$(SUBDIRS))) $(foreach t,$(TARGETS),$(addsuffix $t,$(SUBDIRS)))
GO_DEPS := github.com/kubernetes/deployment-manager/util/... github.com/kubernetes/deployment-manager/version/... github.com/kubernetes/deployment-manager/expandybird/... github.com/kubernetes/deployment-manager/resourcifier/... github.com/kubernetes/deployment-manager/manager/... github.com/kubernetes/deployment-manager/client/... GO_DEPS := github.com/kubernetes/deployment-manager/util/... github.com/kubernetes/deployment-manager/version/... github.com/kubernetes/deployment-manager/expandybird/... github.com/kubernetes/deployment-manager/resourcifier/... github.com/kubernetes/deployment-manager/manager/... github.com/kubernetes/deployment-manager/dm/...
.PHONY : all build test clean $(TARGETS) $(SUBDIRS_TARGETS) .project .docker .PHONY : all build test clean $(TARGETS) $(SUBDIRS_TARGETS) .project .docker
build:
go get -v $(GO_DEPS)
go install -v $(GO_DEPS)
all: build all: build
clean: clean:
...@@ -16,10 +20,6 @@ clean: ...@@ -16,10 +20,6 @@ clean:
test: build test: build
-go test -v $(GO_DEPS) -go test -v $(GO_DEPS)
build:
go get -v $(GO_DEPS)
go install -v $(GO_DEPS)
push: container push: container
container: .project .docker container: .project .docker
......
README.md
View file @ fb94165b
# Deployment Manager # Deployment Manager
Deployment Manager lets you define and deploy simple declarative configuration [![Go Report Card](http://goreportcard.com/badge/kubernetes/deployment-manager)](http://goreportcard.com/report/kubernetes/deployment-manager)
for your Kubernetes resources (e.g., pods, replication controllers, services, etc.).
You can also use Python or [Jinja](http://jinja.pocoo.org/) to create powerful Deployment Manager (DM) provides parameterized templates for Kubernetes clusters.
parameterizable abstract types called **Templates**. You can create general
abstract building blocks to reuse, like a
[Replicated Service](examples/guestbook/replicatedservice.py), or create
more concrete types like a [Redis cluster](examples/guestbook/redis.jinja).
You can find more examples of Templates and configurations in our You can use it deploy ready-to-use types, such as:
[examples](examples). * [Replicated Service](types/replicatedservice/v1)
* [Redis](types/redis/v1)
Deployment Manager uses the same concepts and languages as As you can see, types live in ordinary Github repositories. This repository is a
[Google Cloud Deployment Manager](https://cloud.google.com/deployment-manager/overview), DM type registry.
but creates resources within your Kubernetes cluster, not on the Google Cloud Platform.
Please join us on [the Google Group](https://groups.google.com/forum/#!forum/kubernetes-sig-config) and/or in [the Slack chat room](https://kubernetes.slack.com/messages/sig-configuration/) for the
Kubernetes configuration SIG.
## Getting started You can also use DM to deploy simple templates that use existing types, such as:
* [Guestbook](examples/guestbook/guestbook.yaml)
* [Deployment Manager](examples/bootstrap/bootstrap.yaml)
There are two ways to get started... As you can see, a template is just a `YAML` file that supplies parameters to
instantiate types. (Yes, you're reading that second example correctly. It uses DM
to deploy itself. See [examples/bootstrap/README.md](examples/bootstrap/README.md)
for more information)
* The quick way simply installs Deployment Manager in your cluster using DM runs server side, on your Kubernetes cluster, so it can tell you what types
kubectl. This is the fastest way to get started and takes only a few seconds. you've instantiated in the cluster, and even what resources comprise a given instance.
So, you can ask questions like:
* Show me all the Redis slaves running in this cluster.
* Show me all the resources used by Redis.
* The interesting way bootstraps Deployment Manager, by building and running a Because DM stores its state in the cluster, not on your workstation, you can ask
local instance on your machine, and then using it to install another instance those questions from any client at any time.
in your cluster. You might want to go this way if you're interested in contributing
to Deployment Manager.
Both assume that you have a Kubernetes cluster up and running, and that you can Please hang out with us in
run `kubectl` commands against it. They both also assume that that you're working [the Slack chat room](https://kubernetes.slack.com/messages/sig-configuration/)
with a clone of the repository installed in the src folder of your GOPATH, per and/or
convention. [the Google Group](https://groups.google.com/forum/#!forum/kubernetes-sig-config)
for the Kubernetes configuration SIG. Your feedback and contributions are welcome.
Instructions for the quick install follow here. Instructions for bootstrapping ## Installing Deployment Manager
Deployment Manager can be found in [examples/bootstrap/README.md](examples/bootstrap/README.md).
### Quick Install Follow these 3 steps to install DM:
1. Make sure your Kubernetes cluster is up and running, and that you can run
For the quick install, you're going to use `kubectl` to create the replication `kubectl` commands against it.
controllers and services that comprise a Deployment Manager instance from a predefined 1. Clone this repository into the src folder of your GOPATH, if you haven't already.
configuration file, as follows: 1. Use `kubectl` to intall DM into your cluster:
``` ```
kubectl create -f install.yaml kubectl create -f install.yaml
``` ```
That's it. You should now be able to see Deployment Manager running in your cluster That's it. You can now use `kubectl` to see DM running in your cluster:
using:
``` ```
kubectl get pod,rc,service kubectl get pod,rc,service
``` ```
If you see replication controllers named expandybird-rc, manager-rc and resourcifier-rc If you see expandybird-service, manager-service, resourcifier-service, and
with pods that are READY, and services with corresponding names, then Deployment expandybird-rc, manager-rc and resourcifier-rc with pods that are READY, then DM
Manager is up and running. is up and running!
Note that you can also tear down Deployment Manager using the same file, with: The easiest way to interact with Deployment Manager is through `kubectl` proxy:
``` ```
kubectl delete -f install.yaml kubectl proxy --port=8001 &
``` ```
The easiest way to interact with Deployment Manager, now that it's up and running, This command starts a proxy that lets you interact with the Kubernetes api
is to use a `kubectl` proxy: server through port 8001 on localhost. `dm` uses
`http://localhost:8001/api/v1/proxy/namespaces/default/services/manager-service:manager`
as the default service address for DM.
## Using Deployment Manager
You can use `dm` to deploy a type from the command line. This command deploys a
redis cluster with two workers from the type definition in this repository:
``` ```
kubectl proxy --port=8001 & dm deploy redis/v1
``` ```
This command will start a proxy that lets you interact with the Kubernetes api When you deploy a type, you can optionally supply values for input parameters,
server through port 8001 on you local host. However, there are other ways to access like this:
Deployment Manager. We won't go into them here, but if you know how to access
services running on Kubernetes, you should be able to use any of the supported ```
methods to access Deployment Manager. dm --properties workers=3 deploy redis/v1
```
### Deploying your first application (Guestbook) When you deploy a type, `dm` generates a template from the type and input
paramaters, and then deploys it.
Next, you're going to deploy the canonical guestbook example to your Kubernetes You can also deploy an existing template, or read one from `stdin`. This command
cluster. deploys the canonical Guestbook example from the examples directory:
``` ```
client --name guestbook --service=http://localhost:8001/api/v1/proxy/namespaces/default/services/manager-service:manager examples/guestbook/guestbook.yaml dm deploy examples/guestbook/guestbook.yaml
``` ```
You should now have guestbook up and running. To verify, get the list of services You can now use `kubectl` to see Guestbook running:
running on the cluster:
``` ```
kubectl get service kubectl get service
``` ```
You should see frontend-service running. If your cluster supports external Look for frontend-service. If your cluster supports external load balancing, it
load balancing, it will have an external IP assigned to it, and you should be will have an external IP assigned to it, and you can navigate to it in your browser
able to navigate to it in your browser to see the guestbook in action. to see the guestbook in action.
For more information about this example, see [examples/guestbook/README.md](examples/guestbook/README.md)
## Additional commands
The command line tool makes it easy to configure a cluster from a set of predefined
types.
## Uninstalling Deployment Manager
You can uninstall Deployment Manager using the same configuration file:
```
kubectl delete -f install.yaml
```
## Creating a type registry
All you need to create a type registry is a Github repository with top level file
named `registry.yaml`, and a top level folder named `types` that contains type definitions.
A type definition is just a folder that contains one or more versions, like `/v1`,
`/v2`, etc.
A version is just a folder that contains a type definition. As you can see from the
examples above, a type definition is just a Python or [Jinja](http://jinja.pocoo.org/)
file plus an optional schema.
## Building the container images ## Building the container images
This project runs Deployment Manager on Kubernetes as three replicated services. This project runs Deployment Manager on Kubernetes as three replicated services.
By default, prebuilt images stored in Google Container Registry are used to create By default, install.yaml uses prebuilt images stored in Google Container Registry
them. However, you can build your own container images and push them to your own to install them. However, you can build your own container images and push them
project in the registry. to your own project in the Google Container Registry:
To build and push your own images to Google Container Registry, first set the 1. Set the environment variable PROJECT to the name of a project known to gcloud.
environment variable PROJECT to the name of a project known to gcloud. Then, run 1. Run the following command:
the following command:
``` ```
make push make push
...@@ -123,7 +154,13 @@ available. ...@@ -123,7 +154,13 @@ available.
The project is still under active development, so you might run into issues. If The project is still under active development, so you might run into issues. If
you do, please don't be shy about letting us know, or better yet, contributing a you do, please don't be shy about letting us know, or better yet, contributing a
fix or feature. We use the same contribution conventions as the main Kubernetes fix or feature. We use the same [development process](CONTRIBUTING.md) as the main
repository. Kubernetes repository.
## Relationship to Google Cloud Platform
DM uses the same concepts and languages as
[Google Cloud Deployment Manager](https://cloud.google.com/deployment-manager/overview),
but creates resources in Kubernetes clusters, not in Google Cloud Platform projects.
client/client.go → dm/dm.go
View file @ fb94165b
...@@ -16,9 +16,9 @@ package main ...@@ -16,9 +16,9 @@ package main
import ( import (
"github.com/ghodss/yaml" "github.com/ghodss/yaml"
"github.com/kubernetes/deployment-manager/client/registry"
"github.com/kubernetes/deployment-manager/expandybird/expander" "github.com/kubernetes/deployment-manager/expandybird/expander"
"github.com/kubernetes/deployment-manager/manager/manager" "github.com/kubernetes/deployment-manager/manager/manager"
"github.com/kubernetes/deployment-manager/registry"
"bytes" "bytes"
"encoding/json" "encoding/json"
...@@ -36,7 +36,7 @@ import ( ...@@ -36,7 +36,7 @@ import (
) )
var ( var (
action = flag.String("action", "deploy", "expand | deploy | list | get | delete | update | listtypes | listtypeinstances | types") action = flag.String("action", "deploy", "expand | deploy | list | get | delete | update | list-types | list-instances | types")
name = flag.String("name", "", "Name of template or deployment") name = flag.String("name", "", "Name of template or deployment")
service = flag.String("service", "http://localhost:8001/api/v1/proxy/namespaces/default/services/manager-service:manager", "URL for deployment manager") service = flag.String("service", "http://localhost:8001/api/v1/proxy/namespaces/default/services/manager-service:manager", "URL for deployment manager")
type_registry = flag.String("registry", "kubernetes/deployment-manager", "Type registry [owner/repo], defaults to kubernetes/deployment-manager") type_registry = flag.String("registry", "kubernetes/deployment-manager", "Type registry [owner/repo], defaults to kubernetes/deployment-manager")
...@@ -102,9 +102,9 @@ func main() { ...@@ -102,9 +102,9 @@ func main() {
case "update": case "update":
path := fmt.Sprintf("deployments/%s", name) path := fmt.Sprintf("deployments/%s", name)
callService(path, "PUT", name, readTemplate(name)) callService(path, "PUT", name, readTemplate(name))
case "listtypes": case "list-types":
callService("types", "GET", name, nil) callService("types", "GET", name, nil)
case "listtypeinstances": case "list-instances":
path := fmt.Sprintf("types/%s/instances", url.QueryEscape(name)) path := fmt.Sprintf("types/%s/instances", url.QueryEscape(name))
callService(path, "GET", name, nil) callService(path, "GET", name, nil)
default: default:
......
examples/bootstrap/README.md
View file @ fb94165b
# Bootstrapping Deployment Manager # Bootstrapping Deployment Manager
Welcome to the bootstrap example. The instructions below will step you through Welcome to the bootstrap example. The instructions below will step you through
the process of building and running a local instance of Deployment Manager on the process of building and running a local instance of DM on your local machine,
your local machine, and then using it to deploy another instance in your cluster. and then using it to deploy another instance of DM in your cluster.
This example provides insights into how Deployment Manager works, and is This example provides insights into how DM works, and is recommended for anyone
recommended for anyone interested in contributing to the project. interested in contributing to the project.
The instructions below assume that you have a Kubernetes cluster up and running, ## Prerequisites
and that you can run `kubectl` commands against it. They also assume that that
you're working with a clone of the repository installed in the src folder of your
GOPATH and that your PATH contains `$GOPATH/bin`, per convention.
## Installing required python packages Before you can bootstrap DM, the following prerequisites must be satisfied.
### Kubernetes cluster and go configuration
1. Make sure your Kubernetes cluster is up and running, and that you can run
`kubectl` commands against it.
1. Clone this repository into the src folder of your GOPATH, if you haven't already.
1. Make sure your PATH contains `$GOPATH/bin`.
### Installing required python packages
Since Deployment Manager uses Python and will be running locally on your Since Deployment Manager uses Python and will be running locally on your
machine, you will first need to make sure the necessary Python packages are machine, you need to make sure the necessary Python packages are installed. This
installed. This assumes that you have already installed the pip package step assumes that you have already installed the pip package management system
management system on your machine. on your machine.
``` ```
sudo pip install -r expandybird/requirements.txt pip install -r expandybird/requirements.txt
``` ```
## Building and installing the binaries Note: depending on how you installed python and pip, you may need to use `sudo`
for this command.
## Bootstrapping Deployment Manager
With the prerequisites satisfied, you're ready to bootstrap DM.
Next, you're going to build and install the Deployment Manager binaries. You can ### Building and installing the binaries
do this by running make in the repository root.
First, you're going to build and install the DM binaries. You can do this by
running make in the repository root.
``` ```
make make
``` ```
## Bootstrapping Deployment Manager
Now, you're ready to bootstrap Deployment Manager into the cluster.
### Start Deployment Manager on localhost ### Start Deployment Manager on localhost
First, start the three Deployment Manager binaries on localhost using the supplied Next, start the three DM binaries on localhost using the supplied bootstrap script.
bootstrap script.
``` ```
./examples/bootstrap/bootstrap.sh ./examples/bootstrap/bootstrap.sh
...@@ -54,14 +62,12 @@ It also starts kubectl proxy on port 8001. ...@@ -54,14 +62,12 @@ It also starts kubectl proxy on port 8001.
### Deploy Deployment Manager into your cluster ### Deploy Deployment Manager into your cluster
Next, use the Deployment Manager running on localhost to deploy itself onto the Finally, use the DM running on localhost to deploy another instance of DM onto
cluster using the supplied command line tool and template. the cluster using `dm` and the supplied template.
``` ```
client --name test --service=http://localhost:8080 examples/bootstrap/bootstrap.yaml dm --name DM --service=http://localhost:8080 examples/bootstrap/bootstrap.yaml
``` ```
You should now have Deployment Manager running on your cluster, and it should be You now have Deployment Manager running on your cluster. You can see it running
visible using kubectl (kubectl get pod,rc,service). using `kubectl`, as described in the top level [README.md](../../README.md).
examples/guestbook/README.md
View file @ fb94165b
# Guestbook Example # Guestbook Example
Guestbook example shows how to bring up the Welcome to the Guestbook example. It shows you how to build and reuse
[Guestbook Example](https://github.com/kubernetes/kubernetes/tree/master/examples/guestbook) parameterized templates.
from Kubernetes using Deployment Manager. It also shows you how to construct
and reuse parameterized templates.
## Getting started ## Prerequisites
It is assumed that you have bootstrapped the Deployment Manager on your cluster First, make sure DM is installed in your Kubernetes cluster and that the
by following the [README.md][https://github.com/kubernetes/deployment-manager/blob/master/README.md] Guestbook example is deployed by following the instructions in the top level
for bootstrapping the cluster. [README.md](../../README.md).
## Deploying Guestbook ## Understanding the Guestbook example template
To deploy the Guestbook example, you run the following command.
``` Let's take a closer look at the template used by the Guestbook example.
client --name guestbook --service=http://localhost:8001/api/v1/proxy/namespaces/default/services/manager-service:manager examples/guestbook/guestbook.yaml
``` ### Replicated services
The typical design pattern for microservices in Kubernetes is to create a
replication controller and a service with the same selector, so that the service
exposes ports from the pods managed by the replication controller.
We have created a parameterized type for this kind of replicated service called
[Replicated Service](../../types/replicatedservice/v1), and we use it three times in this
example.
Note that the type is defined by a
[python script](../../types/replicatedservice/v1/replicatedservice.py). It also has a
[schema](../../types/replicatedservice/v1/replicatedservice.py.schema). Schemas are
optional. If present in the type definition, they are used to validate uses of the
type that appear in DM templates.
For more information about types and templates, see the [design document](../../docs/design/design.md).
### Replicated Service ### The Guestbook application
The Guestbook application consists of 2 microservices: a front end and a Redis cluster.
Typical pattern for deploying microservices in Kubernetes is to create both a #### The front end
Replication Controller and a Service. We have created a parameterizable type
for that called [Replicated Service](https://github.com/kubernetes/deployment-manager/tree/master/examples/replicatedservice) The front end is a replicated service with 3 replicas:
that we use throughout this example.
The Guestbook example consists of 2 services, a frontend and a Redis service.
Frontend is a replicated service with 3 replicas and is created like so:
``` ```
- name: frontend - name: frontend
type: https://raw.githubusercontent.com/kubernetes/deployment-manager/master/examples/replicatedservice/replicatedservice.py type: https://raw.githubusercontent.com/kubernetes/deployment-manager/master/examples/replicatedservice/replicatedservice.py
...@@ -38,8 +49,14 @@ Frontend is a replicated service with 3 replicas and is created like so: ...@@ -38,8 +49,14 @@ Frontend is a replicated service with 3 replicas and is created like so:
image: gcr.io/google_containers/example-guestbook-php-redis:v3 image: gcr.io/google_containers/example-guestbook-php-redis:v3
``` ```
Redis is a composite type and consists of two replicated services. A master with a single replica (Note that we use the URL for the type replicatedservice.py, not just the type name.)
and the slaves with 2 replicas. It's construced as follows:
#### The Redis cluster
The Redis cluster consists of two replicated services: a master with a single replica
and the slaves with 2 replicas. It's defined by [this composite type](../../types/redis/v1/redis.jinja),
which is a [Jinja](http://jinja.pocoo.org/) template with a [schema](../../types/redis/v1/redis.jinja.schema).
``` ```
{% set REDIS_PORT = 6379 %} {% set REDIS_PORT = 6379 %}
{% set WORKERS = properties['workers'] or 2 %} {% set WORKERS = properties['workers'] or 2 %}
...@@ -77,22 +94,27 @@ resources: ...@@ -77,22 +94,27 @@ resources:
### Displaying types ### Displaying types
You can also see what types have been deployed to the cluster: You can see the types you deployed to the cluster using the `list-types` command:
``` ```
client --action listtypes --service=http://localhost:8001/api/v1/proxy/namespaces/default/services/manager-service:manager dm list-types
["Service","ReplicationController","redis.jinja","https://raw.githubusercontent.com/kubernetes/deployment-manager/master/examples/replicatedservice/replicatedservice.py"] ["Service","ReplicationController","redis.jinja","https://raw.githubusercontent.com/kubernetes/deployment-manager/master/examples/replicatedservice/replicatedservice.py"]
``` ```
This shows that there are 2 native types that we have deployed (Service and ReplicationController) and This output shows 2 primitive types (Service and ReplicationController), and 2
2 composite types (redis.jinja and one imported from github (replicatedservice.py)). composite types (redis.jinja and one imported from github (replicatedservice.py)).
You can also see where a specific type is being used with the `list-instances` command:
You can also see where the types are being used by getting details on the particular type:
``` ```
client -action gettype --service=http://localhost:8001/api/v1/proxy/namespaces/default/services/manager-service:manager -name 'Service' dm --name 'Service' list-instances
[{"name":"frontend-service","type":"Service","deployment":"guestbook4","manifest":"manifest-1446682551242763329","path":"$.resources[0].resources[0]"},{"name":"redis-master","type":"Service","deployment":"guestbook4","manifest":"manifest-1446682551242763329","path":"$.resources[1].resources[0].resources[0]"},{"name":"redis-slave","type":"Service","deployment":"guestbook4","manifest":"manifest-1446682551242763329","path":"$.resources[1].resources[1].resources[0]"}] [{"name":"frontend-service","type":"Service","deployment":"guestbook4","manifest":"manifest-1446682551242763329","path":"$.resources[0].resources[0]"},{"name":"redis-master","type":"Service","deployment":"guestbook4","manifest":"manifest-1446682551242763329","path":"$.resources[1].resources[0].resources[0]"},{"name":"redis-slave","type":"Service","deployment":"guestbook4","manifest":"manifest-1446682551242763329","path":"$.resources[1].resources[1].resources[0]"}]
``` ```
It lists which deployment and manifest as well as JSON path to the type. This output describes the deployment and manifest, as well as the JSON paths to
the instances of the type within the layout.
For more information about deployments, manifests and layouts, see the [design document](../../docs/design/design.md).
registry.yaml 0 → 100644
View file @ fb94165b
######################################################################
# Copyright 2015 The Kubernetes Authors All rights reserved.
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
# http://www.apache.org/licenses/LICENSE-2.0
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
######################################################################
root: .
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment