Skip to content

Latest commit

 

History

History
204 lines (140 loc) · 5.64 KB

client.md

File metadata and controls

204 lines (140 loc) · 5.64 KB
Raw

Using the Client

updatectl lets you control and test the CoreOS update service. Subcommands let you manage applications, users, groups, packages and write a very simple client that gets its state via environment variables.

Administrative Flags

There are a few flags that you must provide to the administrative commands below.

  • --user is your username, usually this is an email address or admin
  • --key is your API key
  • --server is the URL to your update service instance

The commands below will all have a prefix like this:

./bin/updatectl --user=admin --key=d3b07384d113edec49eaa6238ad5ff00 --server=https://example.update.core-os.net

If you do not wish to specify these every time, they can also be exported as environment variables like this:

export UPDATECTL_USER=admin
export UPDATECTL_KEY=d3b07384d113edec49eaa6238ad5ff00
export UPDATECTL_SERVER=http://localhost:8000

Update Clients

There are two tools to test out the update service: instance fake and watch. instance fake simulates a number of clients from a single command. watch is used to quickly implement a simple update client with a minimal amount of code.

Fake Instances

This example will start 132 fake instances pinging the update service every 1 to 50 seconds against the CoreOS application's UUID and put them in the beta group starting at version 1.0.0.

./bin/updatectl instance fake --clients-per-app=132 --min-sleep=1 \
	--max-sleep=50 --app-id=e96281a6-d1af-4bde-9a0a-97b76e56dc57 \
	--group-id=beta --version=1.0.0

Update Watcher

Real clients should implement the Omaha protocol but if you want a fast way to create your own client you can use watch. This will exec a program of your choosing every time a new update is available.

First, create a simple application that dumps the environment variables that the watcher will pass in. Call the script updater.sh.

#!/bin/sh
env | grep UPDATE_SERVICE

Next we will generate a random client UUID and start watching for changes to the given app:

./bin/updatectl watch --app-id=e96281a6-d1af-4bde-9a0a-97b76e56dc57 \
	--group-id=beta ./updater.sh

If you change the version of the beta group's channel then your script will be re-executed and you will see the UPDATE_SERVICE environment variables change.

Application Management

Applications have three pieces of data: a universal unique identifier (UUID), a label and a description. During a request to the update service, the UUID is submitted in order to retrieve the details of the currently available version.

Add an Application

Create an application called CoreOS using its UUID along with a nice description.

./bin/updatectl app create --app-id=e96281a6-d1af-4bde-9a0a-97b76e56dc57 --label="CoreOS" --description="Linux for Servers"

List Applications

./bin/updatectl app list

Package Management

Packages represent an individual version of an application and the URL associated with it.

Add an Application Version

This will create a new package with version 1.0.5 from the file update.gz.

./bin/updatectl package create --app-id=e96281a6-d1af-4bde-9a0a-97b76e56dc57 \
	--version=1.0.5 --file=update.gz \

The --meta option allows you to specify a cryptographic signature and file size for verification purposes. It should look like this:

{"metadata_size":"1024", "metadata_signature_rsa":"<insert hash here>"}

List Application Versions

./bin/updatectl package list --app-id=e96281a6-d1af-4bde-9a0a-97b76e56dc57

Channel Management

A channel gives a nice symbolic name to packages. A group tracks a specific channel. Think of channels as a DNS name for a package.

Update a channel

A channel has a version of individual applications. To change the version of an application specify the app id, channel and the version that channel should present. Additionally you can publish a channel by setting the --publish flag, if not specified publish will always be set to false.

./bin/updatectl channel update --app-id=e96281a6-d1af-4bde-9a0a-97b76e56dc57 --channel=master --version=1.0.1 --publish=true

Group Management

Instances get their updates by giving the service a combination of their group and application id. Groups are usually some division of data centers, environments or customers.

Creating a Group

Create a group for the CoreOS application pointing at the master channel called testing. This group might be used in your test environment.

./bin/updatectl group create --app-id=e96281a6-d1af-4bde-9a0a-97b76e56dc57 \
	--channel=master --group-id=testing --label="Testing Group"

Pausing Updates on a Group

./bin/updatectl group pause --app-id=e96281a6-d1af-4bde-9a0a-97b76e56dc57 --group-id=testing

List Groups

./bin/updatectl group list
Label           Token                                   UpdatesPaused
Default Group   default                                 false

Instance Management

The service keeps track of instances and gives you a number of tools to see their state. Most of these endpoints are more nicely consumed via the control panel but you can use them from updatectl too.

List Instances

This will list all instances that have been seen since the given timestamp.

./bin/updatectl instance list-updates --start=1392401442

This will list the instances grouped by AppId and Version

./bin/updatectl instance list-app-versions --start=1392401442

User management

Create a new user

./bin/updatectl admin-user create [email protected]

List users

./bin/updatectl admin-user list

Delete a new user

./bin/updatectl admin-user delete [email protected]