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  `