launchpad.net/~rogpeppe/juju-core/500-errgo-fix@v0.0.0-20140213181702-000000002356/cmd/juju/help_topics.go (about) 1 // Copyright 2013 Canonical Ltd. 2 // Licensed under the AGPLv3, see LICENCE file for details. 3 4 package main 5 6 const helpBasics = ` 7 Juju -- devops distilled 8 https://juju.ubuntu.com/ 9 10 Juju provides easy, intelligent service orchestration on top of environments 11 such as Amazon EC2, HP Cloud, OpenStack, MaaS, or your own local machine. 12 13 Basic commands: 14 juju init generate boilerplate configuration for juju environments 15 juju bootstrap start up an environment from scratch 16 17 juju deploy deploy a new service 18 juju add-relation add a relation between two services 19 juju expose expose a service 20 21 juju help bootstrap more help on e.g. bootstrap command 22 juju help commands list all commands 23 juju help glossary glossary of terms 24 juju help topics list all help topics 25 26 Provider information: 27 juju help azure use on Windows Azure 28 juju help ec2 use on Amazon EC2 29 juju help hpcloud use on HP Cloud 30 juju help local use on this computer 31 juju help openstack use on OpenStack 32 ` 33 34 const helpProviderStart = ` 35 Start by generating a generic configuration file for Juju, using the command: 36 37 juju init 38 39 This will create the '~/.juju/' directory (or $JUJU_HOME, if set) if it doesn't 40 already exist and generate a file, 'environments.yaml' in that directory. 41 ` 42 const helpProviderEnd = ` 43 See Also: 44 45 juju help init 46 juju help bootstrap 47 48 ` 49 50 const helpLocalProvider = ` 51 The local provider is a linux-only Juju environment that uses LXC containers as 52 a virtual cloud on the local machine. Because of this, lxc and mongodb are 53 required for the local provider to work. If you don't already have lxc and 54 mongodb installed, run the following commands: 55 56 sudo apt-get update 57 sudo apt-get install lxc mongodb-server 58 59 After that you might get error for SSH authorized/public key not found. ERROR 60 SSH authorized/public key not found. 61 62 ssh-keygen -t rsa 63 64 Now you need to tell Juju to use the local provider and then bootstrap: 65 66 juju switch local 67 sudo juju bootstrap 68 69 The first time this runs it might take a bit, as it's doing a netinstall for 70 the container, it's around a 300 megabyte download. Subsequent bootstraps 71 should be much quicker. 'sudo' is needed because only root can create LXC 72 containers. After the initial bootstrap, you do not need 'sudo' anymore, 73 except to 'sudo juju destroy-environment' when you want to tear everything 74 down. 75 76 You deploy charms from the charm store using the following commands: 77 78 juju deploy mysql 79 juju deploy wordpress 80 juju add-relation wordpress mysql 81 82 References: 83 84 http://askubuntu.com/questions/65359/how-do-i-configure-juju-for-local-usage 85 https://juju.ubuntu.com/docs/getting-started.html 86 ` 87 88 const helpOpenstackProvider = ` 89 Here's an example OpenStack configuration: 90 91 sample_openstack: 92 type: openstack 93 # Specifies whether the use of a floating IP address is required to 94 # give the nodes a public IP address. Some installations assign public 95 # IP addresses by default without requiring a floating IP address. 96 # use-floating-ip: false 97 # Specifies whether new machine instances should have the "default" 98 # Openstack security group assigned. 99 # use-default-secgroup: false 100 admin-secret: 13850d1b9786065cadd0f477e8c97cd3 101 # Globally unique swift bucket name 102 control-bucket: juju-fd6ab8d02393af742bfbe8b9629707ee 103 # Usually set via the env variable OS_AUTH_URL, but can be specified here 104 # auth-url: https://yourkeystoneurl:443/v2.0/ 105 # override if your workstation is running a different series to which 106 # you are deploying 107 # The following are used for userpass authentication (the default) 108 auth-mode: userpass 109 # Usually set via the env variable OS_USERNAME, but can be specified here 110 # username: <your username> 111 # Usually set via the env variable OS_PASSWORD, but can be specified here 112 # password: <secret> 113 # Usually set via the env variable OS_TENANT_NAME, but can be specified here 114 # tenant-name: <your tenant name> 115 # Usually set via the env variable OS_REGION_NAME, but can be specified here 116 # region: <your region> 117 118 References: 119 120 http://juju.ubuntu.com/docs/provider-configuration-openstack.html 121 http://askubuntu.com/questions/132411/how-can-i-configure-juju-for-deployment-on-openstack 122 123 Other OpenStack Based Clouds: 124 125 This answer is for generic OpenStack support, if you're using an OpenStack-based 126 provider check these questions out for provider-specific information: 127 128 https://juju.ubuntu.com/docs/config-hpcloud.html 129 130 ` 131 132 const helpEC2Provider = ` 133 Configuring the EC2 environment requires telling Juju about your AWS access key 134 and secret key. To do this, you can either set the 'AWS_ACCESS_KEY_ID' and 135 'AWS_SECRET_ACCESS_KEY' environment variables[1] (as usual for other EC2 tools) 136 or you can add access-key and secret-key options to your environments.yaml. 137 These are already in place in the generated config, you just need to uncomment 138 them out. For example: 139 140 sample_ec2: 141 type: ec2 142 # access-key: YOUR-ACCESS-KEY-GOES-HERE 143 # secret-key: YOUR-SECRET-KEY-GOES-HERE 144 control-bucket: juju-faefb490d69a41f0a3616a4808e0766b 145 admin-secret: 81a1e7429e6847c4941fda7591246594 146 147 See the EC2 provider documentation[2] for more options. The S3 bucket does not 148 need to exist already. 149 150 Note If you already have an AWS account, you can determine your access key by 151 visiting your account page[3], clicking "Security Credentials" and then clicking 152 "Access Credentials". You'll be taken to a table that lists your access keys and 153 has a "show" link for each access key that will reveal the associated secret 154 key. 155 156 And that's it, you're ready to go! 157 158 References: 159 160 [1]: http://askubuntu.com/questions/730/how-do-i-set-environment-variables 161 [2]: https://juju.ubuntu.com/docs/provider-configuration-ec2.html 162 [3]: http://aws.amazon.com/account 163 164 More information: 165 166 https://juju.ubuntu.com/docs/getting-started.html 167 https://juju.ubuntu.com/docs/provider-configuration-ec2.html 168 http://askubuntu.com/questions/225513/how-do-i-configure-juju-to-use-amazon-web-services-aws 169 ` 170 171 const helpHPCloud = ` 172 HP Cloud is an Openstack cloud provider. To deploy to it, use an openstack 173 environment type for Juju, which would look something like this: 174 175 sample_hpcloud: 176 type: openstack 177 tenant-name: "juju-project1" 178 auth-url: https://region-a.geo-1.identity.hpcloudsvc.com:35357/v2.0/ 179 auth-mode: userpass 180 username: "xxxyour-hpcloud-usernamexxx" 181 password: "xxxpasswordxxx" 182 region: az-1.region-a.geo-1 183 184 See the online help for more information: 185 186 https://juju.ubuntu.com/docs/config-hpcloud.html 187 ` 188 189 const helpAzureProvider = ` 190 A generic Windows Azure environment looks like this: 191 192 sample_azure: 193 type: azure 194 # Location for instances, e.g. West US, North Europe. 195 location: West US 196 # http://msdn.microsoft.com/en-us/library/windowsazure 197 # Windows Azure Management info. 198 management-subscription-id: 886413e1-3b8a-5382-9b90-0c9aee199e5d 199 management-certificate-path: /home/me/azure.pem 200 # Windows Azure Storage info. 201 storage-account-name: juju0useast0 202 # Override OS image selection with a fixed image for all deployments. 203 # Most useful for developers. 204 # force-image-name: b39f27a8b8c64d52b05eac6a62ebad85__Ubuntu-13_10-amd64-server-DEVELOPMENT-20130713-Juju_ALPHA-en-us-30GB 205 # Pick a simplestreams stream to select OS images from: daily or released 206 # images, or any other stream available on simplestreams. Leave blank for 207 # released images. 208 # image-stream: "" 209 210 This is the environments.yaml configuration file needed to run on Windows Azure. 211 You will need to set the management-subscription-id, management-certificate- 212 path, and storage-account-name. 213 214 Note: Other than location, the defaults are recommended, but can be updated to 215 your preference. 216 217 See the online help for more information: 218 219 https://juju.ubuntu.com/docs/config-azure.html 220 ` 221 222 const helpConstraints = ` 223 Constraints constrain the possible instances that may be started by juju 224 commands. They are usually passed as a flag to commands that provision a new 225 machine (such as bootstrap, deploy, and add-machine). 226 227 Each constraint defines a minimum acceptable value for a characteristic of a 228 machine. Juju will provision the least expensive machine that fulfills all the 229 constraints specified. Note that these values are the minimum, and the actual 230 machine used may exceed these specifications if one that exactly matches does 231 not exist. 232 233 If a constraint is defined that cannot be fulfilled by any machine in the 234 environment, no machine will be provisioned, and an error will be printed in the 235 machine's entry in juju status. 236 237 Constraint defaults can be set on an environment or on specific services by 238 using the set-constraints command (see juju help set-constraints). Constraints 239 set on the environment or on a service can be viewed by using the get- 240 constraints command. In addition, you can specify constraints when executing a 241 command by using the --constraints flag (for commands that support it). 242 243 Constraints specified on the environment and service will be combined to 244 determine the full list of constraints on the machine(s) to be provisioned by 245 the command. Service-specific constraints will override environment-specific 246 constraints, which override the juju default constraints. 247 248 Constraints are specified as key value pairs separated by an equals sign, with 249 multiple constraints delimited by a space. 250 251 Constraint Types: 252 253 arch 254 Arch defines the CPU architecture that the machine must have. Currently 255 recognized architectures: 256 amd64 (default) 257 i386 258 arm 259 260 cpu-cores 261 Cpu-cores is a whole number that defines the number of effective cores the 262 machine must have available. 263 264 mem 265 Mem is a float with an optional suffix that defines the minimum amount of RAM 266 that the machine must have. The value is rounded up to the next whole 267 megabyte. The default units are megabytes, but you can use a size suffix to 268 use other units: 269 270 M megabytes (default) 271 G gigabytes (1024 megabytes) 272 T terabytes (1024 gigabytes) 273 P petabytes (1024 terabytes) 274 275 root-disk 276 Root-Disk is a float that defines the amount of space in megabytes that must 277 be available in the machine's root partition. For providers that have 278 configurable root disk sizes (such as EC2) an instance with the specified 279 amount of disk space in the root partition may be requested. Root disk size 280 defaults to megabytes and may be specified in the same manner as the mem 281 constraint. 282 283 container 284 Container defines that the machine must be a container of the specified type. 285 A container of that type may be created by juju to fulfill the request. 286 Currently supported containers: 287 none - (default) no container 288 lxc - an lxc container 289 kvm - a kvm container 290 291 cpu-power 292 Cpu-power is a whole number that defines the speed of the machine's CPU, 293 where 100 CpuPower is considered to be equivalent to 1 Amazon ECU (or, 294 roughly, a single 2007-era Xeon). Cpu-power is currently only supported by 295 the Amazon EC2 environment. 296 297 tags 298 Tags defines the list of tags that the machine must have applied to it. 299 Multiple tags must be delimited by a comma. Tags are currently only supported 300 by the MaaS environment. 301 302 Example: 303 304 juju add-machine --constraints "arch=amd64 mem=8G tags=foo,bar" 305 306 See Also: 307 juju help set-constraints 308 juju help get-constraints 309 juju help deploy 310 juju help add-unit 311 juju help add-machine 312 juju help bootstrap 313 ` 314 315 const helpGlossary = ` 316 Bootstrap 317 To boostrap an environment means initializing it so that Services may be 318 deployed on it. 319 320 Charm 321 A Charm provides the definition of the service, including its metadata, 322 dependencies to other services, packages necessary, as well as the logic for 323 management of the application. It is the layer that integrates an external 324 application component like Postgres or WordPress into Juju. A Juju Service may 325 generally be seen as the composition of its Juju Charm and the upstream 326 application (traditionally made available through its package). 327 328 Charm URL 329 A Charm URL is a resource locator for a charm, with the following format and 330 restrictions: 331 332 <schema>:[~<user>/]<collection>/<name>[-<revision>] 333 334 schema must be either "cs", for a charm from the Juju charm store, or "local", 335 for a charm from a local repository. 336 337 user is only valid in charm store URLs, and allows you to source charms from 338 individual users (rather than from the main charm store); it must be a valid 339 Launchpad user name. 340 341 collection denotes a charm's purpose and status, and is derived from the 342 Ubuntu series targeted by its contained charms: examples include "precise", 343 "quantal", "oneiric-universe". 344 345 name is just the name of the charm; it must start and end with lowercase 346 (ascii) letters, and can otherwise contain any combination of lowercase 347 letters, digits, and "-"s. 348 349 revision, if specified, points to a specific revision of the charm pointed to 350 by the rest of the URL. It must be a non-negative integer. 351 352 Endpoint 353 The combination of a service name and a relation name. 354 355 Environment 356 An Environment is a configured location where Services can be deployed onto. 357 An Environment typically has a name, which can usually be omitted when there's 358 a single Environment configured, or when a default is explicitly defined. 359 Depending on the type of Environment, it may have to be bootstrapped before 360 interactions with it may take place (e.g. EC2). The local environment 361 configuration is defined in the ~/.juju/environments.yaml file. 362 363 Machine Agent 364 Software which runs inside each machine that is part of an Environment, and is 365 able to handle the needs of deploying and managing Service Units in this 366 machine. 367 368 Provisioning Agent 369 Software responsible for automatically allocating and terminating machines in 370 an Environment, as necessary for the requested configuration. 371 372 Relation 373 Relations are the way in which Juju enables Services to communicate to each 374 other, and the way in which the topology of Services is assembled. The Charm 375 defines which Relations a given Service may establish, and what kind of 376 interface these Relations require. 377 378 In many cases, the establishment of a Relation will result into an actual TCP 379 connection being created between the Service Units, but that's not necessarily 380 the case. Relations may also be established to inform Services of 381 configuration parameters, to request monitoring information, or any other 382 details which the Charm author has chosen to make available. 383 384 Repository 385 A location where multiple charms are stored. Repositories may be as simple as 386 a directory structure on a local disk, or as complex as a rich smart server 387 supporting remote searching and so on. 388 389 Service 390 Juju operates in terms of services. A service is any application (or set of 391 applications) that is integrated into the framework as an individual component 392 which should generally be joined with other components to perform a more 393 complex goal. 394 395 As an example, WordPress could be deployed as a service and, to perform its 396 tasks properly, might communicate with a database service and a load balancer 397 service. 398 399 Service Configuration 400 There are many different settings in a Juju deployment, but the term Service 401 Configuration refers to the settings which a user can define to customize the 402 behavior of a Service. 403 404 The behavior of a Service when its Service Configuration changes is entirely 405 defined by its Charm. 406 407 Service Unit 408 A running instance of a given Juju Service. Simple Services may be deployed 409 with a single Service Unit, but it is possible for an individual Service to 410 have multiple Service Units running in independent machines. All Service Units 411 for a given Service will share the same Charm, the same relations, and the 412 same user-provided configuration. 413 414 For instance, one may deploy a single MongoDB Service, and specify that it 415 should run 3 Units, so that the replica set is resilient to failures. 416 Internally, even though the replica set shares the same user-provided 417 configuration, each Unit may be performing different roles within the replica 418 set, as defined by the Charm. 419 420 Service Unit Agent 421 Software which manages all the lifecycle of a single Service Unit. 422 423 ` 424 425 const helpLogging = ` 426 Juju has logging available for both client and server components. Most 427 users' exposure to the logging mechanism is through either the 'debug-log' 428 command, or through the log file stored on the bootstrap node at 429 /var/log/juju/all-machines.log. 430 431 All the agents have their own log files on the individual machines. So 432 for the bootstrap node, there is the machine agent log file at 433 /var/log/juju/machine-0.log. When a unit is deployed on a machine, 434 a unit agent is started. This agent also logs to /var/log/juju and the 435 name of the log file is based on the id of the unit, so for wordpress/0 436 the log file is unit-wordpress-0.log. 437 438 Juju uses rsyslog to forward the content of all the log files on the machine 439 back to the bootstrap node, and they are accumulated into the all-machines.log 440 file. Each line is prefixed with the source agent tag (also the same as 441 the filename without the extension). 442 443 Juju has a hierarchical logging system internally, and as a user you can 444 control how much information is logged out. 445 446 Output from the charm hook execution comes under the log name "unit". 447 By default Juju makes sure that this information is logged out at 448 the DEBUG level. If you explicitly specify a value for unit, then 449 this is used instead. 450 451 Juju internal logging comes under the log name "juju". Different areas 452 of the codebase have different anmes. For example: 453 providers are under juju.provider 454 workers are under juju.worker 455 database parts are under juju.state 456 457 All the agents are started with all logging set to DEBUG. Which means you 458 see all the internal juju logging statements until the logging worker starts 459 and updates the logging configuration to be what is stored for the environment. 460 461 You can set the logging levels using a number of different mechanisms. 462 463 environments.yaml 464 - all environments support 'logging-config' as a key 465 - logging-config: ... 466 environment variable 467 - export JUJU_LOGGING_CONFIG='...' 468 setting the logging-config at bootstrap time 469 - juju bootstrap --logging-config='...' 470 juju set-environment logging-config='...' 471 472 Configuration values are separated by semicolons. 473 474 Examples: 475 476 juju set-environment logging-config "juju=WARNING; unit=INFO" 477 478 Developers may well like: 479 480 export JUJU_LOGGING_CONFIG='juju=INFO; juju.current.work.area=TRACE' 481 482 Valid logging levels: 483 CRITICAL 484 ERROR 485 WARNING 486 INFO 487 DEBUG 488 TRACE 489 `