github.com/sap/cf-mta-plugin@v2.6.3+incompatible/README.md (about)

     1  <p align="center"><img width="335" height="281" src="logo.png" alt="MultiApps logo"></p>
     2  
     3  # MultiApps CF CLI Plugin [![Build Status](https://travis-ci.org/cloudfoundry-incubator/multiapps-cli-plugin.svg?branch=master)](https://travis-ci.org/cloudfoundry-incubator/multiapps-cli-plugin)
     4  This is a Cloud Foundry CLI plugin (formerly known as CF MTA Plugin) for performing operations on [multi-target applications (MTAs)](https://www.sap.com/documents/2016/06/e2f618e4-757c-0010-82c7-eda71af511fa.html) in Cloud Foundry, such as deploying, removing, viewing, etc. It is a client for the [CF MultiApps Controller](https://github.com/cloudfoundry-incubator/multiapps-controller) (formerly known as CF MTA deploy-service), which is an MTA deployer implementation for Cloud Foundry.
     5  
     6  # Requirements
     7  - Installed CloudFoundry CLI - ensure that CloudFoundry CLI is installed and working. For more information about installation of CloudFoundry CLI, please visit the official CloudFoundry [documentation](https://docs.cloudfoundry.org/cf-cli/install-go-cli.html). CloudFoundry CLI v7 beta is not supported. You need to have v6.4x
     8  - Working [CF MultiApps Controller](https://github.com/cloudfoundry-incubator/multiapps-controller) - this a CF plugin for the MultiApps Controller application. Thus, a working MultiApps Controller must be available on the CF landscape
     9  
    10  # Download and Installation
    11  
    12  :rotating_light: Check whether you have a previous version installed, using the command: `cf plugins`. If the MtaPlugin is already installed, you need to uninstall it first and then to install the new version. You can uninstall the plugin using command `cf uninstall-plugin MtaPlugin`.
    13  
    14  ## CF Community Plugin Repository
    15  
    16  The MultiApps CF CLI Plugin is now also available on the CF Community Repository. To install the latest available version of the MultiApps CLI Plugin execute the following:
    17  
    18  `cf install-plugin multiapps`
    19  
    20  If you do not have the community repository in your CF CLI you can add it first by executing:
    21  
    22  `cf add-plugin-repo CF-Community https://plugins.cloudfoundry.org`
    23  
    24  ## Manual Installation
    25  
    26  Alternatively you can install any version of the plugin by manually downloading it from the releases page and installing the binaries for your specific operating system.
    27  
    28  ### Download
    29  The latest version of the plugin can also be downloaded from the project's [releases](https://github.com/cloudfoundry-incubator/multiapps-cli-plugin/releases/latest/). Download the plugin for your platform (Darwin, Linux, Windows). The name for the correct plugin for each platform can be found in the table below.
    30  
    31  Mac OS X 64 bit | Windows 32 bit | Windows 64 bit | Linux 32 bit | Linux 64 bit
    32  --- | --- | --- | --- | ---
    33  multiapps-plugin.osx | multiapps-plugin.win32 | multiapps-plugin.win64 | multiapps-plugin.linux32 | multiapps-plugin.linux64
    34  
    35  ### Installation
    36  Install the plugin, using the following command:
    37  ```
    38  cf install-plugin <path-to-the-plugin> -f
    39  ```
    40  :rotating_light: Note: if you are running on an Unix-based system, you need to make the plugin executable before installing it. In order to achieve this, execute the following commad `chmod +x <path-to-the-plugin>`
    41  
    42  ## Usage
    43  The MultiApps CF plugin supports the following commands:
    44  
    45  Command Name | Command Description
    46  --- | ---
    47  `deploy` | Deploy a new multi-target app or sync changes to an existing one
    48  `undeploy` | Undeploy (remove) a multi-target app
    49  `mtas` | List all multi-target apps
    50  `mta` | Display health and status for a multi-target app
    51  `mta-ops` | List active multi-target app operations
    52  `download-mta-op-logs` / `dmol` | Download logs of multi-target app operation
    53  `bg-deploy` | Deploy a multi-target app using blue-green deployment
    54  `purge-mta-config` | Purge stale configuration entries
    55  
    56  For more information, see the command help output available via `cf [command] --help` or `cf help [command]`.
    57  
    58  Here is an example deployment of the open-sourced [spring-music](https://github.com/nvvalchev/spring-music):
    59  ```
    60  git clone https://github.com/nvvalchev/spring-music.git
    61  cf deploy mta-assembly/spring-music.mtar -e config.mtaext
    62  ```
    63  
    64  # Configuration     
    65  The configuration of the MultiApps CF plugin is done via env variables. The following are supported:
    66  * `DEBUG=1` - Enables the logging of HTTP requests in `STDOUT` and `STDERRR`.
    67  * `MULTIAPPS_CONTROLLER_URL=<URL>` - By default, the plugin attempts to deduce the multiapps-controller URL based on the available shared domains. In case of issues, or if you want to target a non-default multiapps-controller instance, you can configure the targeted URL via this env variable.
    68  * `MULTIAPPS_UPLOAD_CHUNK_SIZE=<POSITIVE_INTEGER>` - By default, large MTARs are not uploaded as a single unit, but are split up into smaller chunks of 45 MBs that are uploaded separately. The goal is to prevent failed uploads due to [gorouter](https://github.com/cloudfoundry/gorouter)'s request timeout. In case the default chunk size is still too large, you can configure it via this environment variable. **The specified values are in megabytes.**
    69  :rotating_light: Note: The total number of chunks in which an MTAR is split cannot exceed 50, since the multiapps-controller could interpret bigger values as a denial-of-service attack. For this reason, the minimum value for this environment variable is computed based on the formula: `MIN = MTAR_SIZE / 50`
    70  For example, with a 100MB MTAR the minimum value for this environment variable would be 2, and for a 400MB MTAR it would be 8. Finally, the minimum value cannot grow over 50, so with a 4GB MTAR, the minimum value would be 50 and not 80.
    71  
    72  # How to contribute
    73  * [Did you find a bug?](CONTRIBUTING.md#did-you-find-a-bug)
    74  * [Do you have a question or need support?](CONTRIBUTING.md#do-you-have-a-question-or-need-support)
    75  * [How to develop, test and contribute to MultiApps CF Plugin](CONTRIBUTING.md#do-you-want-to-contribute-to-the-code-base)
    76  
    77  # Development
    78  
    79  *WARNING* : with [Issue 117](https://github.com/cloudfoundry-incubator/multiapps-cli-plugin/issues/117) the master branch of this repository as well as other artifacts will be renamed. Adaptation to any CI/CD infrastructure & scritps will be required.
    80  
    81  ## Cloning the repository
    82  To clone the project in your Go workspace `$GOPATH/src/github.com/cloudfoundry-incubator/multiapps-cli-plugin` execute the following commands:
    83  ```
    84  mkdir -p $GOPATH/src/github.com/cloudfoundry-incubator
    85  cd $GOPATH/src/github.com/cloudfoundry-incubator
    86  git clone git@github.com:cloudfoundry-incubator/multiapps-cli-plugin.git
    87  ```
    88  
    89  ## Building new release version
    90  You can automatically build new release for all supported platforms by calling the build.sh script with the version of the build.
    91  The version will be automatically included in the plugin, so it will be reported by `cf plugins`.
    92  
    93  :rotating_light: Note that the version parameter should follow the semver format (e.g. 1.2.3).
    94  ```bash
    95  ./build.sh 1.2.3
    96  ```
    97  
    98  This will produce `mta_plugin_linux_amd64`, `mta_plugin_darwin_amd64` and `mta_plugin_windows_amd64` in the repo's root directory.
    99  
   100  ## Adding dependency into the multiapps-cli-plugin
   101  #### If you want to add a dependecy which to be used later on during the build and development process, you need to follow these steps:
   102  1.  Make sure that you have godep installed(try to run `godep version`). If you do not have it, run the command: `go get github.com/tools/godep`. !!!IMPORTANT!!! Make sure that you are running on latest version of GO and godep!!!
   103  2.  Get the dependency by executing the command: `go get github.com/<package-full-name>` . If you want to update it use the -u option.
   104  3.  Use the dependecy into your code(just import and use)
   105  4.  Make sure that the dependency is not in the Godeps/Godeps.json file(if it is, delete the entry related to it). Godeps.json file is holding information about all the dependencies which are used in the project.
   106  5.  Run `godep save ./...` - this will add all the newly used dependecies into the Godeps/Godeps.json and into the vendor/ folder.
   107  
   108  For more information about the godep tool, please refer to: [godep](https://github.com/tools/godep)
   109  
   110  # Further reading
   111  Presentations, documents, and tutorials:
   112  - [Managing Distributed Cloud Native Applications Made Easy (CF Summit EU 2017 slides)](https://www.slideshare.net/NikolayValchev/managing-distributedcloudapps-80697059)
   113  - [Managing Distributed Cloud Native Applications Made Easy (CF Summit EU 2017 video)](https://www.youtube.com/watch?v=d07DZCuUXyk&feature=youtu.be)
   114  - [CF orchestration capabilities by tutorial & example](https://github.com/SAP-samples/cf-mta-examples)
   115  
   116  # License
   117  
   118  This project is licensed under the Apache Software License, v. 2 except as noted otherwise in the [LICENSE](https://github.com/cloudfoundry-incubator/multiapps-cli-plugin/blob/master/LICENSE) file.
   119