github.com/cloudbase/juju-core@v0.0.0-20140504232958-a7271ac7912f/doc/glossary.txt (about) 1 Juju Glossary 2 ============= 3 4 This document introduces and briefly explains a number of terms that are used 5 throughout the juju documentation, roughly broken down by conceptual area. The 6 intent of this document is to make the reader aware of the available modes of 7 interaction with juju, and how the various commands and concepts interact. It 8 makes no attempt to be comprehensive; just accurate and opinionated. 9 10 Charms 11 ------ 12 13 A `charm` is a collection of code and data that embodies best practice in 14 the deployment of a particular piece (or collection) of software. Examples 15 of software that has been charmed include: 16 17 * wordpress (blogging platform) 18 * mediawiki (wiki platform) 19 * mysql (relational database) 20 * mongodb (non-relational database) 21 * hadoop (heavyweight data crunching) 22 * glance, keystone, nova-compute, etc (openstack components) 23 * minecraft (game server) 24 25 A charm consists of the following components: 26 27 * metadata (describes the charm's purpose and capabilities) 28 * configuration (describes the ways in which a user can tune the software) 29 * hooks (executables, invoked by juju, that configure and deploy the software) 30 * revision (an integer identifying separate versions of the same charm) 31 * any additional code or data useful to the hooks or the deployed software 32 33 A `charm directory` is a filesystem directory containing the aforementioned 34 components of a charm in standard locations. (Any additional code/data can go 35 anywhere not reserved for the other components.) 36 37 A `charm bundle` is a charm directory serialized as a zip file. This format is 38 used for storage and distribution only; when a charm is deployed it is always 39 unbundled into a charm directory, within which all hooks are executed. 40 41 A `repository` is a collection of charms that can be deployed by juju. 42 43 The `charm store` is the default repository, which serves only curated bundled 44 charms. 45 46 A `local repository` is a repository located on the same system as the juju 47 client. 48 49 A `charm URL` is a string that identifies the provenance and the intended 50 deployment target of a charm, and may also specify the charm's revision. 51 Charms are identified by their charm URLs. 52 53 Environments 54 ------------ 55 56 A `machine` is a computing resource on which components of juju, and of the 57 software deployed by juju, can run. The following command is used to 58 manipulate machines directly. 59 60 * juju terminate-machine (soon to alias destroy-machine) [TODO: not implemented] 61 62 An `environment` is a deployment of juju. It always includes at least one 63 machine responsible for maintaining the system's state, and potentially 64 provisioning additional machines in response to state changes. The following 65 commands are used to manipulate and inspect the environment. 66 67 * juju bootstrap 68 * juju status [TODO: somewhat incomplete] 69 * juju upgrade-juju 70 * juju destroy-environment 71 72 An `environment provider` mediates between juju and the substrate on which an 73 environment runs. Each provider allows juju to run against a different backend: 74 75 * ec2 (Amazon EC2 and S3) 76 * maas (bare metal) [TODO: work in progress] 77 * local (LXC containers on client machine) [TODO: work in progress] 78 * openstack (many public and private clouds) [TODO: work in progress] 79 80 An `environment configuration` describes how to create and connect to an 81 environment from a specific provider. An environment configuration must 82 always specify at least the following information: 83 84 * name (to identify the environment) 85 * type (to specify the provider) 86 * admin-secret (a "password" identifying an client with administrative- 87 level access to system state) 88 * authorized-keys (SSH public keys identifying users allowed to connect to 89 machines in the environment) 90 91 ...and may accept or even require additional keys depending on the provider 92 type; but the full details of environment configuration are outside the scope 93 of this document. 94 95 [TODO: there should/will be commands for inspecting and manipulating the 96 configuration of an environment while it's running; the names "env-get" and 97 "env-set" have been mooted, but I'm not sure that's sane: I can't see any 98 reason not to use the existing "get" and "set", which currently only work 99 for services. But I could just be missing something obvious. Note that certain 100 settings, such as "name" and "type", and "region" in the ec2 provider, will 101 need to be immutable, and I'm not sure whether that's implemented yet.] 102 103 An `environments file` is a YAML file containing environment configurations. 104 Juju cannot operate without a valid environments file, which must be saved at 105 `~/.juju/environments.yaml` on the client machine. 106 107 The simplest functional environments file looks like this: 108 109 environments: 110 aws: 111 type: ec2 112 admin-secret: <password string> 113 control-bucket: <globally unique S3 bucket name> 114 115 The "name" of the single defined environment is determined by its key in the 116 environments map ("aws"), and the "authorized-keys" can be safely omitted so 117 long as the client machine has a public key with a standard name saved in 118 `~/.ssh`. Because it's using the "ec2" provider type, it also has to specify 119 a "control-bucket" key; the "access-key" and "secret-key" settings are also 120 required, but can be omitted if the AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY 121 environment variables are set in the client process. The "region" setting 122 defaults to "us-east-1"; there are other possible settings but they're not 123 relevant here. 124 125 [NOTE: there is much more to environment configuration than has been discussed 126 here. "authorized-keys-path" and "default-series" both apply to every provider, 127 the ec2 provider offers many not mentioned here, and it will only get worse with 128 each new provider...] 129 130 Services 131 -------- 132 133 A `service` is a deployment of a charm in an environment. The following commands 134 are used to manipulate services: 135 136 * juju deploy 137 * juju destroy-service [TODO: not implemented] 138 139 A service's `configuration` is defined by its charm, and allows the user to 140 inspect and tune the service's operation using the following commands: 141 142 * juju get 143 * juju set 144 145 A `unit` is the fundamental component of a service; services are composed of 146 units. Each unit represents an instance of the charm's software, deployed to 147 some machine in the service's environment. The following commands are used to 148 manipulate units: 149 150 * juju add-unit 151 * juju remove-unit (soon to alias destroy-unit) 152 153 [TODO: units are currently not, but will shortly be, deployed to LXC containers 154 within their machines; this prevents units on the same machine from interfering 155 with one another (except when each attempts to open the same port; we haven't 156 worked out how to deal with that yet).] 157 158 A service is `exposed` if it is theoretically accessible from the public 159 internet (or, at least, from outside its environment). The fact of a service's 160 exposure does not necessarily imply that any units of that service are actually 161 accessible; actual access is mediated by the service's units, which are 162 responsible for specifying the ports that should actually be opened when the 163 service is exposed. Service exposure is controlled with the following commands: 164 165 * juju expose 166 * juju unexpose 167 168 [NOTE: the "firewall-mode" environment configuration setting comes into play 169 here, but that may be a topic for a more detailed document, along with the 170 varying levels of firewalling support in the various providers.] 171 172 A service's charm can be `upgraded` when the revision of that charm available 173 from its original repository is greater than that or the service's current charm, 174 and when the following conditions hold: 175 176 * all configuration keys that exist in both versions of the charm must have 177 the same data type (addition or removal of config settings is fine, and it's 178 ok for defaults to change, but (for example) a string cannot become an 179 integer). 180 * any normal relations in which the service is participating must also be 181 available, unchanged, in the newer version of the charm (addition or removal 182 of charm relations is, in general, fine). 183 * [TODO: something to do with storage compatibility, but storage doesn't exist 184 yet] 185 186 The following command is used to upgrade a service's charm: 187 188 * juju upgrade-charm [TODO: not implemented] 189 190 [TODO: --revision and --switch params, that do not exist in the python version, 191 are mooted; they would respectively allow up/downgrades to specific revisions, 192 and crossgrades to entirely different charms, but priority/agreement is unclear.] 193 194 Sometimes (although, hopefully, rarely) a unit will encounter an `error` that 195 requires human intervention. These cases are as follows: 196 197 * a charm hook returned a non-zero exit code 198 * the unit process was killed while running a charm hook 199 * a charm upgrade failed due to conflicting content in the charm directory 200 201 In each of these situations, the unit stops responding to most external events, 202 and waits for an administrator to resolve the problem. The administrator may 203 need to log into the machine with the failed unit to determine and resolve the 204 problem, or he may be able to resolve the problem automatically by trying to 205 re-run the failed hook. The following commands are useful in error recovery: 206 207 * juju ssh 208 * juju scp 209 * juju resolved 210 211 A `forced upgrade` is a form of upgrade that ignores unit error states, and 212 upgrades them anyway. Forced upgrades are subtle and quick to anger; they 213 are only recommended if you have sole control of your environment and a clear 214 understanding of the upgrade process as it applies to your specific charm. 215 216 Relations 217 --------- 218 219 An `interface` is an informally-agreed protocol for transferring information 220 between service units. Examples include: 221 222 * http (hostname, port) 223 * mysql (host, database, user, password, slave) 224 * ceph-client (key, auth, rid) [TODO: I don't think rid is appropriate, we 225 should take a look and figure out if it could be dropped] 226 227 A `role` describes the manner in which a charm uses an interface. A role can 228 have one of three values: "provider", "requirer", or "peer". 229 230 A `(charm) relation` is an entry in a charm's metadata that indicates that it 231 can fulfil some role over some interface. For example, the "relations" section 232 of a charm's metadata might look like this (taken from wordpress): 233 234 requires: 235 db: 236 interface: mysql 237 nfs: 238 interface: mount 239 cache: 240 interface: memcache 241 provides: 242 website: 243 interface: http 244 peers: 245 loadbalancer: 246 interface: reversenginx 247 248 The above defines five (charm) relations, named "db", "nfs", "cache", "website", 249 and "loadbalancer". "db" is a "requirer" over the "mysql" interface; "website" 250 is a "provider" over the "http" interface. 251 252 An `endpoint` is the combination of a service with one of its charm's relations. 253 The set of a service's endpoints define the possible connections involving that 254 service. Within an environment, an endpoint is uniquely identifiable when 255 expressed in the form `<service-name>:<charm-relation-name>`. 256 257 A "normal" `relation` is a connection between the endpoints of two services. 258 The services' charms must respectively "provide" and "require" relations with 259 identical interfaces. When two services are participating in a relation, each 260 unit of each service can communicate with every unit of the other service. 261 Normal relations can be manipulated with the following commands: 262 263 * juju add-relation 264 * juju remove-relation (soon to alias destroy-relation) 265 266 A `(peer) relation` is a connection within a service defined by a single 267 endpoint with the "peer" role. If such an endpoint exists, the peer relation 268 is automatically created when the service is deployed; each unit of the 269 service can communicate with every other unit of the service. Peer relations 270 cannot be manipulated in the UI, but are displayed in `juju status` output. 271 272 The word `relation`, when used casually, *may* refer to a charm relation or a 273 peer relation, but is most likely to refer to a "normal" relation. 274 275 When manipulating relations, it is important to understand that a single 276 endpoint can participate in multiple relations. For example, a mysql:server 277 endpoint can quite happily participate in relations with both a wikimedia:db 278 endpoint and a wordpress:db endpoint (or even in multiple relations with 279 separate services running their own charms: for example, wordpress1:db and 280 wordpress2:db). In each case, the mysql charm is responsible for creating 281 separate users and databases for each separate relation. 282 283 [TODO: charm relations also have a concept of "limit" which probably ought to 284 come in here, but no code respects it at the moment. Oh, and a "required" field 285 too, and I'm not sure whether anyone fully recalls its precise intended 286 semantics... not sure what to do about this.] 287 288 Subordinates 289 ------------ 290 291 [TODO: subordinates are not yet implemented in go, but the vast majority of the 292 building blocks are already integrated.] 293 294 A `subordinate charm` is a charm which declares itself to be subordinate. 295 296 A `subordinate service` is a service running a subordinate charm. 297 298 A `subordinate unit` is a unit of a subordinate service. 299 300 All other charms, services, and units are `principal` units, by virtue of not 301 being subordinate. 302 303 A charm relation's `scope` controls which units within a relation are visible 304 to one another. Most relations have "global" scope, which is the default; a 305 subordinate charm must define at least one relation with "local" scope. 306 307 A normal or peer relation's `scope` is the narrowest scope amongst its 308 endpoints; a normal relation's scope is "global" unless either endpoint has 309 "local" scope, in which case it the whole relation has "local" scope, while a 310 peer relation's single endpoint must always in practice have "global" scope. 311 312 When a subordinate service is deployed, no units are created; the add-unit and 313 remove-unit [TODO: lp:1091634] commands do not apply to subordinate services. 314 Instead, subordinate units are deployed as a side-effect of the creation of 315 locally-scoped relations between the subordinate service and others, and 316 recalled as a result of the destruction of the services or relations they are 317 dependent upon [TODO: lp:1091865]. 318 319 To clarify: when a new relation is added and all the following conditions apply: 320 321 * one service is a subordinate; 322 * one service is a principal; 323 * the relation between the two is locally scoped, by virtue of at least one 324 of the endpoints having local scope: 325 326 ...a new unit of the subordinate service will be created and deployed alongside 327 each unit of the principal service (unless one already exists). Each principal 328 unit is responsible for its own associated subordinate, which runs alongside 329 the principal with essentially identical privileges. Due to the local scoping 330 of the relation, each subordinate unit responds only to the principal unit that 331 deployed it, and vice versa. 332 333 [TODO: to clarify: once units are deployed inside their own containers, subordinate 334 units will be installed inside their principal unit's container. But we don't have 335 containers yet.] 336 337 A subordinate service can of course participate in globally-scoped relations as 338 well; such relations can be added as normal, and the subordinate units participate 339 in those relations just as in any other global relation. 340 341 [NOTE: there's also a magic implicit charm relation, called "juju-info", which 342 provides the "juju-info" interface and allows subordinates to establish relations 343 with arbitrary principals. Couldn't really figure out how to work it in nicely.] 344 345 Constraints 346 ----------- 347 348 [TODO: constraints are not yet implemented in go; a substantial amount of work 349 needs to be done] 350 351 Some environment providers offer the ability to provision machines with varying 352 characteristics. An environment provider defines a vocabulary of `constraints` 353 to control the computing resources that are available from the provider; by 354 specifying global environment constraints and overriding them where necessary 355 at the service level, a user can ensure that her workloads are only run on 356 machines with appropriate characteristics. 357 358 Available constraints vary by provider, and are manipulated and inspected using 359 the following commands: 360 361 * juju set-constraints (not implemented) 362 * juju get-constraints (not implemented) 363 364 Storage 365 ------- 366 367 [TODO: storage remains an informally-specified concept distributed across 368 several brains; don't even try to document it.] 369 370 Entity lifecycles 371 ----------------- 372 373 When services, relations, units and machines are added and destroyed by the 374 client, changes to the environment will take some time to occur: in particular, 375 destruction is rarely instantaneous. Destroyed entities will continue to be 376 displayed in juju status output but marked as "dying" [TODO: they are not] until 377 the underlying resources have been removed. 378 379 This is not really worth worrying about in general, but it does mean that after 380 a service or relation has been destroyed you will need to wait until they have 381 been *removed* before you're able to add a new service or relation with the same 382 name. It's not an issue for units or machines, because their names are assigned 383 internally by juju and are guaranteed to be unique.