pivotal-cf / docs-on-demand-service-broker

Documentation for the On Demand Service Broker SDK

docs-on-demand-service-broker

This repo contains the On-Demand Services SDK documentation.

In this README:

• docs-on-demand-service-broker
  • Branches
  • Releasing a new minor version
  • Partials
  • Contributing to documentation
  • Publishing docs
    • Prepare Markdown files
    • In Docsdash
    • Promoting to pre-prod and prod
  • Troubleshooting Markdown
  • Style Guide

Branches

The main branch is the tree-trunk, so always make changes you want carried forward in this branch. This includes:

• Unreleased features
• Doc bug fixes
• Doc reorganization or enhancement

Then, if necessary, immediately cherry-pick/copy any changes that you want to push immediately to production into the appropriate branches listed below:

Branch name	Use for
main	Unreleased v0.46
v0.45	Staging and Prod
v0.44	Staging and Prod
v0.43.x	Staging and Prod
v0.42.x	Staging and Prod
v0.41.x	Out of support. PDF only
v0.40.x	Out of support. PDF only
v0.39.x	Out of support. PDF only
v0.38.x	Out of support. PDF only
v0.37.x	Out of support. PDF only
v0.36.x	Out of support. PDF only
v0.35.x	Out of support. PDF only
v0.34.x	Out of support. PDF only
v0.33.x	Out of support. PDF only
v0.32.x	Out of support. PDF only
v0.31.x	Out of support. PDF only
v0.30.x	Out of support. PDF only
v0.29.x	Out of support. PDF only
v0.28.x	Out of support. PDF only
v0.27.x	Out of support. PDF only
v0.26.x	Out of support. PDF only
v0.25.x	Out of support. PDF only
v0.24.x	Out of support. PDF only
v0.23.x	Out of support. PDF only
v0.22.x	Out of support. PDF only
v0.21.x	Out of support. PDF only
v0.20.x	obsolete, but do not delete the branch. PDF only
v0.19.x	obsolete, but do not delete the branch. PDF only
v0.18.x	obsolete, but do not delete the branch. PDF only
v0.17.x	obsolete, but do not delete the branch. PDF only
v0.16.x	obsolete, but do not delete the branch. PDF only
v0.15.x	obsolete, but do not delete the branch. PDF only
v0.14.x	obsolete, but do not delete the branch
v0.13.x	obsolete, but do not delete the branch
v0.12.x	obsolete, but do not delete the branch
v0.11.x	obsolete, but do not delete the branch
v0.10.x	obsolete, but do not delete the branch
v0.9.x	obsolete, but do not delete the branch

Releasing a new minor version

Because main is the latest and greatest documentation, the process is to cut a x.x branch for the version that main was targeting during that time.

After this point, main is the target for the next version of the On-Demand Services SDK product.

Partials

Cross-product partials (if any) for On-Demand Services SDK are single sourced from the Docs Partials repository.

Contributing to documentation

If there is some documentation to add for an unreleased patch version of Cloud Service Broker then create a branch off of the live branch you intend to modify and create a pull request against that branch. After the version that change is targeting is released, the pull request can be merged and will be live the next time a documentation deployment occurs.

If the documentation is meant to be target several released versions, then you will need to:

• create a pull request for each individual minor version
• or ask the technical writer to cherry-pick to particular branches/versions.

For instructions on how to create a pull request on a branch and instructions on how to create a pull request using a fork, see Creating a PR in the documentation team wiki.

Publishing docs

• docworks is the main tool for managing docs used by writers.
• docsdash is a deployment UI which manages the promotion from staging to pre-prod to production. The process below describes how to upload our docs to staging, replacing the publication with the same version.

Prepare Markdown files

• Markdown files live in this repo.
• Images should live in an images directory at the same level and linked with a relative link.
• Each page requires an entry in config/toc.md for the table of contents.
• Variables live in config/template_variables.yml.

In Docsdash

1. Wait about 1 minute for processing to complete after uploading.

2. Go to https://docsdash.vmware.com/deployment-stage

   There should be an entry with a blue link which says Documentation and points to staging.

Promoting to pre-prod and prod

Prerequisite Needs additional privileges: reach out to a manager on the docs team #tanzu-docs or ask a writer to do this step for you.

1. Go to Staging publications in docsdash https://docsdash.vmware.com/deployment-stage

2. Select a publication (make sure it's the latest version)

3. Click Deploy selected to Pre-Prod and wait for the pop to turn green. If necessary, refresh after about 10 seconds.

4. Go to the Pre-Prod list: https://docsdash.vmware.com/deployment-pre-prod

5. Select a publication

6. Click Sign off for Release

7. Wait for your username to show up in the "Signed off by" column

8. Select the publication again

9. Click Deploy selected to Prod

Troubleshooting Markdown

Problem	List displays as a paragraph
Symptom:	Bulleted or numbered lists look fine on GitHub but display as a single paragraph in HTML.
Solution:	Add a blank line after the stem sentence and before the first item in the list.

Problem	List numbering is broken: every item is 1.
Symptom:	Each numbered item in a list is a 1. instead of 1., 2., 3., etc
Solution:	Try removing any blank newlines within each step.

Problem	Code boxes not showing
Symptom:	VMware publishing system doesn't accept code tags after the three back ticks.
Solution:	Make sure you're not using shell or bash or console or yaml after back ticks.

Style Guide

This is a word list for terminology and word usage specific to the On-Demand Services SDK for docs.

docs-on-demand-service-broker's Issues

Loggregator no longer uses etcd

@avade I've been combing through the Pivotal docs for mentions of etcd and noticed we mention etcd in the ODB SDK "Operating" topic: https://github.com/pivotal-cf/docs-on-demand-service-broker/blob/v0.15.x/operating.html.md.erb#L285.

Now that Loggregator no longer uses etcd, should we remove those lines?

Upgrade-All 'GET instances' Errand flow not completely correct

In the Upgrade-All, the sequence diagram illustrates a 'GET instances' line between the Errand and Cloud Controller.

However, for full completeness there should be a line between the Errand and the ODB 'GET instances' and then from ODB to CC 'GET instances' and then the return lines back to the errand. This helps illustrate that the Upgrade-All errand never talks to CC and doesn't have a client to do so.

It would be nice to have ODB/On Demand Broker and Cloud Controller/CF labels consistent in the diagrams.

Please configure GITBOT

Pivotal uses GITBOT to synchronize Github issues and pull requests with Pivotal Tracker.
Please add your new repo to the GITBOT config-production.yml in the Gitbot configuration repo.
If you don't have access you can send an ask ticket to the CF admins. We prefer teams to submit their changes via a pull request.

Steps:

• Fork this repo: cfgitbot-config
• Add your project to config-production.yml file
• Submit a PR

If there are any questions, please reach out to [email protected].

cloud config ip ranges conflict w/ OOTB cf-release deployment

Under step 5, the cloud-config.yml (as pictured) specifies an IP range (10.244.0.0/24) and gateway (10.244.0.1) the conflicts with the OOTB cf-release. Not a big deal to figure out, but it would probably make for a more pleasant working-through-the-example experience.

Link to Kafka app doesn't work

On one of the getting started pages for the ODB(https://docs.pivotal.io/svc-sdk/odb/0-15/getting-started.html) the link to the kafka example app(https://github.com/pivotal-cf-experimental/kafka-example-app) is not working.

pivotal cloud foundry throwing error with node

• I am trying to include node agent in my pcf.
• but I am getting below error after I execute this command cf restage webcomponent
  Failed to compile droplet: Failed to run all supply scripts: exit status 14
  Exit status 223
  Staging failed: STG: Exited with status 223
• can you tell me how to fix it.
• am I doing anything wrong with my environment variables of pcf

refrence link https://docs.appdynamics.com/display/PRO42/Install+the+Node.js+Agent
https://docs.pivotal.io/pivotalcf/1-12/buildpacks/node/node-tips.html#env-var

User Provided Environment Variables

GRANT_TYPE                   implicit
OPTIMIZE_MEMORY              true
SSO_IDENTITY_PROVIDERS       uaa
http_proxy                   http://proxy.blanket.com:80
https_proxy                  http://proxy.blanket.com:80
Name                         Value

environment variables

{
  "staging_env_json": {},
  "running_env_json": {},
  "system_env_json": {
    "VCAP_SERVICES": {
      "p-identity": [
        {
          "credentials": {
            "client_id": "788787878723232323873287",
            "client_secret": "ewqyueyuewuwi87323287ejhwweiu",
            "auth_domain": "https://app-luagh.com"
          },
          "syslog_drain_url": null,
          "volume_mounts": [],
          "label": "p-identity",
          "provider": null,
          "plan": "app-auth",
          "name": "sso",
          "tags": []
        }
      ],
      "user-provided": [
        {
          "credentials": {
            "uri": "http://we.laugh.com"
          },
          "syslog_drain_url": "",
          "volume_mounts": [],
          "label": "user-provided",
          "name": "crystalreports",
          "tags": []
        }
      ],
      "appdynamics": [
        {
          "credentials": {
            "account-name": "technology-blanket",
            "port": "78787878",
            "account-access-key": "fdae8266e8b3",
            "host-name": "technology-blanket.saas.appdynamics.com",
            "ssl-enabled": "true"
          },
          "syslog_drain_url": null,
          "volume_mounts": [],
          "label": "appdynamics",
          "provider": null,
          "plan": "AppDynamics",
          "name": "appdynamics",
          "tags": [
            "appdynamics",
            "apm",
            "mobile real-user monitoring",
            "browser real-user monitoring",
            "database monitoring",
            "server monitoring",
            "application analytics"
          ]
        }
      ]
    }
  },
  "application_env_json": {
    "VCAP_APPLICATION": {
      "cf_api": "https://api.wdhjhj.laugh.com",
      "limits": {
        "fds": 16384,
        "mem": 8192,
        "disk": 2048
      },
      "application_name": "webcomponent",
      "application_uris": [
        "here.laugh.com"
      ],
      "name": "webcomponent",
      "space_name": "app-DEV",
      "space_id": "aeryuryw2872jk32iuk",
      "uris": [
        "here.laugh.com"
      ],
      "users": null,
      "application_id": "jkdsjkdsjk89989889",
      "version": "yuwrhjyuwuyw-237823878723kj",
      "application_version": "yhjjhhjhj-yuyuuy877887"
    }
  }
}

$ cf restage webcomponent

Restaging app webcomponent in org example-app / space sublime-text as 788781287...

Staging app and tracing logs...
   Downloading build artifacts cache...
   Downloaded app package (6M)
   Downloaded build artifacts cache (26.2M)
   Staging...
   -----> Download go 1.9
   -----> Running go build supply
   -----> Nodejs Buildpack version 1.6.8
   -----> Installing binaries
          engines.node (package.json): unspecified
          engines.npm (package.json): unspecified (use default)
   -----> Installing node 4.8.4
          Download [https://buildpacks.cloudfoundry.org/dependencies/node/node-4.8.4-linux-x64-230101ff.tgz]
          **WARNING** Node version not specified in package.json. See: http://docs.cloudfoundry.org/buildpacks/node/node-tips.html
          Using default npm version: 2.15.11
   -----> Installing yarn 1.1.0
          Download [https://buildpacks.cloudfoundry.org/dependencies/yarn/yarn-v1.1.0-26588f71.tar.gz]
          Installed yarn 1.1.0
   -----> Creating runtime environment
          NODE_HOME=/tmp/contents811454074/deps/0/node
          PRO TIP: It is recommended to vendor the application's Node.js dependencies
          Visit http://docs.cloudfoundry.org/buildpacks/node/index.html#vendoring
          NODE_ENV=production
          NODE_MODULES_CACHE=true
          NODE_VERBOSE=false
          NPM_CONFIG_LOGLEVEL=error
          NPM_CONFIG_PRODUCTION=true
          - .npm
   -----> Restoring cache
          Loading 3 from cacheDirectories (default):
          - bower_components (not cached - skipping)
          - .cache/yarn (not cached - skipping)
          Installing node modules (package.json)
   -----> Building dependencies
   > [email protected] postinstall /tmp/app/node_modules/uglifyjs-webpack-plugin
   > node lib/post_install.js
   > [email protected] postinstall /tmp/app
   > webpack -p --config ./webpack.prod.js --progress --profile --bail
    10% building modules 0/1 modules 1 active ...der/src/index.js!/tmp/app/app/main.ts
   [at-loader] Using [email protected] from typescript and "tsconfig.json" from /tmp/app/tsconfig.json.
 30% building modules 174/183 modules 9 active .../app/app/services/animalsService.ts
 49% building modules 333/374 modules 41 active ...ar/http/src/backends/browser_jsonp.js
 67% building modules 519/537 modules 18 active ...ar/router/src/routlib/zlib/adler32.js
 69% building modules 698/707 modules 9 active ...mponents/title/titles-allocation.html
54382ms building modules
   37ms sealing
   0ms basic module optimization
   1ms optimizing
   1ms chunk optimization
   42ms module optimization
   0ms advanced chunk optimization
   0ms basic chunk optimization
   0ms advanced module optimization
   0ms chunk modules optimization
   0ms module and chunk tree optimization
   0ms advanced chunk modules optimization
   12ms module reviving
   8ms module order optimization
   5ms module id optimization
   0ms chunk order optimization
   0ms chunk reviving
   20ms chunk id optimization
   88ms hashing
   1ms module assets processing
   164ms chunk assets processing
   238ms additional chunk assets processing
   0ms recording
   95741ms additional asset processing
    94% asset optimization
   [at-loader] Checking started in a separate process...
   1ms chunk asset optimization
   [at-loader] Checking finished with 4 errors
7885ms asset optimization
   198ms emitting
       app.js  6.48 MB       0  [emitted]  [big]  app
   index.html  2.38 kB          [emitted]
      [6] ./app/mobile/mobile.service.ts 2.38 kB {0} [built]
      [7] ./app/services/nailService.ts 3.19 kB {0} [built]
          [] -> factory:9141ms building:209ms dependencies:674ms = 10024ms
          [] -> factory:92ms building:1167ms dependencies:9284ms = 10543ms
          [] -> factory:3595ms building:118ms dependencies:755ms = 4468ms
    [497] ./app/main.ts 7.37 kB {0} [built]
          [] -> factory:35ms building:756ms dependencies:42213ms = 43004ms
    [625] ./app/app.component.ts 53.9 kB {0} [built]
          [] -> factory:47ms building:1654ms dependencies:26464ms = 28165ms
       + 817 hidden modules
   ERROR in [at-loader] ./app/components/swimming-birds/playing-birds-laughing.ts:8316:50
       TS2341: Property 'allData' is private and only accessible within class 'playingrcap'.
          [0] ./node_modules/html-webpack-plugin/lib/loader.js!./app/index.html 2.52 kB {0} [built]
   Hash: 6ad9b11d2fa7af59bf00
   Version: webpack 3.7.1
   Time: 158876ms
          [] -> factory:10654ms building:378ms dependencies:85ms = 11117ms
          [] -> factory:16964ms building:327ms dependencies:8106ms = 25397ms
          [] -> factory:14883ms building:371ms dependencies:57ms = 15311ms
        Asset     Size  Chunks                    Chunk Names
      [1] ./app/services/SPORTS.service.ts 19.4 kB {0} [built]
     [35] ./app/services/decodeService.ts 3.25 kB {0} [built]
          [] -> factory:7496ms building:440ms dependencies:1ms = 7937ms
          [] -> factory:19193ms building:1177ms dependencies:0ms = 20370ms
          [] -> factory:8435ms building:188ms dependencies:0ms = 8623ms
          [] -> factory:9147ms building:832ms dependencies:7129ms = 17108ms
     [59] ./app/services/egplayingService.ts 3.57 kB {0} [built]
    [304] ./app/mobile/mobilions.ts 563 bytes {0} [built]
    [375] ./app/services/clipboard.service.ts 3.78 kB {0} [built]
     [18] ./app/services/playingService.ts 15 kB {0} [built]
     [70] ./app/services/animalsService.ts 968 bytes {0} [built]
    [133] ./app/services/canDeactivate.service.ts 2.91 kB {0} [built]
           factory:27ms building:6978ms = 7005ms
    [594] ./app/app.module.ts 35 kB {0} [built]
    [789] ./app/app.routing.ts 42.1 kB {0} [built]
          [] -> factory:29907ms building:4964ms dependencies:0ms = 34871ms
    [827] ./app/services/CanActivateViaAuthGuard.ts 1.42 kB {0} [built]
          [] -> factory:29945ms building:5159ms dependencies:2681ms = 37785ms
   45:15-36 Critical dependency: the request of a dependency is an expression
   WARNING in ./node_modules/@angular/core/src/linker/system_js_ng_module_factory_loader.js
   WARNING in ./node_modules/@angular/core/src/linker/system_js_ng_module_factory_loader.js
   57:15-102 Critical dependency: the request of a dependency is an expression
   ERROR in [at-loader] ./app/components/swimming-birds/playing-birds-laughing.ts:8330:43
   ERROR in [at-loader] ./app/components/swimming-birds/playing-birds-laughing.ts:8319:61
   ERROR in [at-loader] ./app/components/swimming-birds/playing-birds-laughing.ts:8370:43
       TS2341: Property 'allData' is private and only accessible within class 'playingrcap'.
       TS2341: Property 'allData' is private and only accessible within class 'playingrcap'.
       TS2341: Property 'allData' is private and only accessible within class 'playingrcap'.
               factory:7018ms building:13ms = 7031ms
        1 asset
   Child html-webpack-plugin for "index.html":
   npm ERR! not with npm itself.
   npm ERR! Or if that isn't available, you can get their info via:
   npm ERR!
   npm ERR!     npm owner ls SPORTS
   npm ERR! Linux 4.4.0-96-generic
   npm ERR! npm  v2.15.11
   npm ERR! node v4.8.4
   npm ERR!
   npm ERR! argv "/tmp/contents811454074/deps/0/node/bin/node" "/tmp/contents811454074/deps/0/bin/npm" "install" "--unsafe-perm" "--userconfig" "/tmp/app/.npmrc" "--cache" "/tmp/app/.npm"
   npm ERR! code ELIFECYCLE
   npm ERR! Exit status 2
   npm ERR!     npm bugs SPORTS
   npm ERR! There is likely additional logging output above.
   npm ERR! This is most likely a problem with the SPORTS package,
   npm ERR! Tell the author that this fails on your system:
   npm ERR! You can get information on how to open an issue for this project with:
   npm ERR! [email protected] postinstall: `webpack -p --config ./webpack.prod.js --progress --profile --bail`
   npm ERR! Failed at the [email protected] postinstall script 'webpack -p --config ./webpack.prod.js --progress --profile --bail'.
   npm ERR!     webpack -p --config ./webpack.prod.js --progress --profile --bail
   npm ERR!     /tmp/app/npm-debug.log
   npm ERR! Please include the following file with any support request:
          **ERROR** Unable to build dependencies: exit status 1
   Failed to compile droplet: Failed to run all supply scripts: exit status 14
   Exit status 223
   Staging failed: STG: Exited with status 223
   Stopping instance affd069e-bf48-4ab4-b613-54913c3abf23
   Destroying container
   Successfully destroyed container
Error staging application: App staging failed in the buildpack compile phase
FAILED