cloudfoundry / docs-dev-guide Goto Github PK
View Code? Open in Web Editor NEWDocumentation for application developers who want to deploy their applications to Cloud Foundry
License: Apache License 2.0
Documentation for application developers who want to deploy their applications to Cloud Foundry
License: Apache License 2.0
We should mention that the cf CLI uses exit codes, useful for scripting: '0' means command was successful, any other value means it failed.
A new section in "Consistent Behavior to Help You Work Efficiently" in installcf/whats-new-v6.html.md.erb may be a good location.
We could include the commands used to check the exit code on each supported platform (Linux/Mac, Windows Command Line, Windows Powershell), as done here http://docs.aws.amazon.com/cli/latest/topic/return-codes.html.
If you look at the table at https://github.com/cloudfoundry/docs-dev-guide/blob/master/deploy-apps/environment-variable.html.md#vcap_application, there is a table of keys and their description for the JSON contained in the VCAP_APPLICATION env var. There is also an example JSON output below the table. The example includes a "uris" key while the table does not.
It looks to me like the "uris" key is identical to "applications_uris", but I don't know for sure. I think this should probably be fixed in the docs, either by removing the "uris" key from the example, or adding the "uris" key as a item in the table.
FWIW, when I looked at the env vars for a running application, I do see the "uris" key.
In deploy-apps/manifest.html.md.erb file, there are manifest examples which use 'subdomain' attribute.
I'm not sure if 'subdomain' is valid. They should be 'host' instead of 'subdomain:'?
https://github.com/cloudfoundry/docs-dev-guide/blob/master/deploy-apps/manifest.html.md.erb#L430
subdomain: tick09875
https://github.com/cloudfoundry/docs-dev-guide/blob/master/deploy-apps/manifest.html.md.erb#L478
subdomain: 321flurry
In large-app-deploy.html page, there is explanation about app startup timeout settings.
I think it's currently hard to understand.
CF_STARTUP_TIMEOUT: Controls the maximum time that the cf CLI waits for an app to start. Value set in minutes.
cf push -t TIMEOUT: Controls the maximum time that the cf CLI waits for an app to start. When you use this flag, cf ignores any app start timeout value set in the manifest or in the CF_STARTUP_TIMEOUT environment variable. Value set in seconds.
According to the description, it looks these 2 timeout settings (actually 3 settings including timeout attribute in manifeset.yml) have completely same meaning, because they have the same explanation ("Controls the maximum time that the cf CLI waits for an app to start"). However, they have different default value (5 min vs 60 sec). Therefore I think this is confusing for readers (Why do different settings exist for one purpose? There are 2 default values, so if I specify nothing, which value is used?).
I was considering what these 3 timeout settings actually mean in following thread:
https://groups.google.com/a/cloudfoundry.org/forum/#!topic/vcap-dev/R4ZtcWo6B0g
My current understanding is:
In short, CF_STARTUP_TIMEOUT is for client only, but cf push -t TIMEOUT and timeout in manifest are for both client and server (I think).
If my understanding is correct, I think the article will be much easy to understand by adding the information (difference of them). For example, I would suggest to add explanation like below:
cf push -t TIMEOUT: Controls the maximum time that the cf CLI waits for an app to start.
to
cf push -t TIMEOUT: Controls the maximum time that the cf CLI waits for an app to start. This also controls the maximum time that Cloud Foundry waits for an app to start at server.
After successful ssh if I execute the mysql command - then I am getting mysql not found error.
Each of the examples currently shows that the CNAME or ALIAS targets yourappname.cfapps.io, implying that the application should have also been mapped to this uri. In reality, during DNS resolution the yourappname part is ignored because of the wildcard entry so it would probably be clearer to say foo.cfapps.io with a footnote explaining this.
I am having problems understanding the runtime hooks documentation at https://docs.run.pivotal.io/devguide/deploy-apps/deploy-app.html#profile.
As far as I understand the documentation, I have to put the .profile
file into the root of my application directory.
My directory structure looks like this when I SSH into the application:
├── app
│ ├── .java-buildpack // omitted
│ └── rest-api-0.0.3
│ ├── bin
│ │ ├── rest-api
│ │ ├── rest-api.bat
│ │ ├── run-minimal.bat
│ │ └── run-minimal.sh
│ ├── docs
│ │ └── index.html
│ ├── lib // omitted
│ └── .profile <-- this is my .profile file
├── .bash_logout
├── .bashrc
├── logs
├── .profile
├── staging_info.yml
├── tmp
└── tree
But the file does not get executed. My .profile
file looks like this:
echo "This is a test." > mytestfile
If it got executed, I would expect a file mytestfile
anywhere in this directory structure.
The .profile
folder outside of my app
directory is not under my control, the only thing the cf
CLI pushed to the server were the contents of the app/
folder.
Where do I have to place the .profile
file in order to get executed?
I am using the java-buildpack and my API endpoint is https://api.run.pivotal.io (API version: 2.61.0)
.
The docs describe CF_INSTANCE_GUID as:
The GUID of the application. [...]
However, applications (running on Diego) appear to have their GUID stored in VCAP_APPLICATION (in "application_id") and this value is not the same as CF_INSTANCE_GUID. So presumably the CF_INSTANCE_GUID is something other than the GUID of the application.
"Services Overview" gives only a basic definition of service key and the link to Managing Service Keys sheds no further light on how service keys operate.
For instance, what use is made of a service key, or the name of a service key, once it has been created? How does a service key relate to an application-service instance binding? Will a binding include the credentials from a service key or is it up to the application developer to provide these credentials to the application by some other means.
Referencing
I ran into an issue where I messed up my cf manifest by specifying a bunk value for "command". When I deleted it and it didn't change anything upon app push, I learned that previous manifest pushes take precedence over blank lines. I eventually figured out how to run my command, but for a bit I was completely lost as to how to turn back my command entry to its default and undo my mistake.
Can we provide instructions for "reseting" manifests? If it depends on language or framework, can we provide specific instructions?
Thanks!
Lee
Every example of a VCAP_APPLICATION environment variable I have found has the space_name attribute set (including examples in the same doc), however the list of VCAP_APPLICATION attributes in deploy-apps/environment-variable.html.md.erb omits it.
Is this intentional?
Thanks,
Docs currently for the Splunk integration (docs-dev-guide/services/integrate-splunk.html.md.erb) specify an outdated approach of sending app data out as syslog. More recently (Jan 2017), @cholick wrote a guest blog post on Splunk.com which shows how to use splunk-firehose-nozzle to get the job done.
Can this docs page be refactored to use this new technique? I see no compelling reason that the historical syslog technique should remain.
http://docs.cloudfoundry.org/buildpacks/ruby/ruby-tips.html#workers
http://docs.pivotal.io/pivotalcf/buildpacks/ruby/ruby-tips.html#workers
Users are asking if adding --no-route
in CLI or no-route: true
in manifest.yml to the worker app sounds better to them, as they should be background worker apps that serve no external requests. Please be advised. Thanks!
I have a CF node app running and I have some functions that need to be called as a part of cleanup on app exit. I have called those cleanup functions on process.exit event. But unfortunately, I am not seeing the clean up happening. Is there any extra parameter that I need to set for this cleanup function to be executed.This is the event listener and cleanup functions I have written
function exitHandler(options, err) {
console.log("INSIDE EXITHANDLER")
if (options.cleanup) console.log("I am Dead")
if (err) console.log(err.stack);
if (options.exit) process.exit();
}
//do something when app is closing
process.on('exit', exitHandler.bind(null,{cleanup:true}));
//catches ctrl+c event
process.on('SIGINT', exitHandler.bind(null, {exit:true}));
process.on('SIGTERM', exitHandler.bind(null, {exit:true}));
// catches "kill pid" (for example: nodemon restart)
process.on('SIGUSR1', exitHandler.bind(null, {exit:true}));
process.on('SIGUSR2', exitHandler.bind(null, {exit:true}));
//catches uncaught exceptions
process.on('uncaughtException', exitHandler.bind(null, {exit:true}));
Hello,
On Services API, we were making some doc changes and noticed this section:
We think this is correct and potentially valuable information, but may not apply to all users or plans. In particular, it's unlikely this would come into play when the user first chooses a service plan. It may be more relevant somewhere that refers to restarting CF or scaling app instances.
Let us know if you need more context as to why this might not belong in the services section.
/cc @mmb
Thanks!
CF Services API
Formatting of the "cf env" command line options at these links doesn't match.
http://docs.cloudfoundry.org/devguide/deploy-apps/manifest.html#env-block
http://docs.run.pivotal.io/devguide/deploy-apps/manifest.html#env-block
http://docs.pivotal.io/pivotalcf/devguide/deploy-apps/manifest.html#env-block
The bullet points don't match with the corresponding command.
Hi, thanks for your work on the documentation. I thought I'd offer some comments from a new user perspective.
https://docs.cloudfoundry.org/devguide/deploy-apps/cf-scale.html
With -i, cf may remove some of my instances. Will it choose these at random? Or the least recently used? Does my app need to take account of the possibility that an instance may be removed while it is serving a request? I assume this is good practice, but wondering how hard the framework tries to insulate me from this situation.
With -m (and -k), I imagine these changes take effect while the app is running. Should I think of this command as changing the memory allocated to the VM? Can that happen in real time, or does the VM need to be paused? If the app uses a JVM with a command line (e.g. -Xmx) argument to set max memory, will cf scale -m restart the app instance?
The link for "Multi-Line Stack Traces as a Single Log Entity" is right above the section - any need to have the link?
The description of the buildpack
attribute in an app manifest could be clearer if it provided an example and/or explanation clarifying what the URL should point to (i.e. a git repo with the buildpack source, or a tarfile containing the buildpack, or something else?)
From blue-green.html.md.erb:
Blue-green deployment is a release technique that reduces downtime and risk
...
Cloud Foundry community members have written plugins to automate the blue-green
release process.
However, blue-green is an app deployment concern, distinct from feature release. From Jez Humble's Four Principles of Low-Risk Software Releases:
Blue-green deployments and canary releasing are examples of applying the second of my four principles: decoupling deployment and release. Deployment is what happens when you install some version of your software into a particular environment (the production environment is often implied). Release is when you make a system or some part of it (for example, a feature) available to users.
...
In this way, we can deploy new versions of our software continuously, completely independently of the decision as to which features are available to which users. Feature toggles can perform this function.
Would like instructions for how to securely use Volume Services with LDAP as of CF v1.12.
using-vol-services.html.md.erb
Thanks!
In Using Blue-Green Deployment to Reduce Downtime and Risk, we provide minimal advice about what to do with Blue after the switch to Green:
You can also decommission Blue, or keep it in case you need to roll back your changes.
What we do with Blue between the Blue-Green deployment and the Green-Blue deployment is a question my last two platform engineering teams have wrestled with. On the one hand, in keeping with immutable infrastructure and deploying :allthethings:, it seems like it'd be best practice to delete Blue before or as part of the Green-Blue deployment, creating an entirely fresh, pristine Blue from the pipeline. Some have expressed concern, though, about losing stateful aspects of the app instance, such as service bindings (and potentially triggering service instance lifecycle events).
What should we do with Blue before switching back to it?
Hello,
I pushed application, but could not start it
2018-04-08T09:05:58.18+0400 [APP/PROC/WEB/0] OUT at Function.Module._load (module.js:497:3) code: 'MODULE_NOT_FOUND' }
2018-04-08T09:05:58.18+0400 [APP/PROC/WEB/0] ERR js-bson: Failed to load c++ bson extension, using pure JS version
2018-04-08T09:05:58.32+0400 [APP/PROC/WEB/0] ERR /home/vcap/app/routes/donations.js:13
2018-04-08T09:05:58.32+0400 [APP/PROC/WEB/0] ERR url = vcap_services['mongolab'][0].credentials.uri;
2018-04-08T09:05:58.32+0400 [APP/PROC/WEB/0] ERR ^
2018-04-08T09:05:58.32+0400 [APP/PROC/WEB/0] ERR TypeError: Cannot read property '0' of undefined
2018-04-08T09:05:58.32+0400 [APP/PROC/WEB/0] ERR at Object. (/home/vcap/app/routes/donations.js:13:33)
2018-04-08T09:05:58.32+0400 [APP/PROC/WEB/0] ERR at Module._compile (module.js:652:30)
2018-04-08T09:05:58.32+0400 [APP/PROC/WEB/0] ERR at Object.Module._extensions..js (module.js:663:10)
2018-04-08T09:05:58.32+0400 [APP/PROC/WEB/0] ERR at Module.load (module.js:565:32)
2018-04-08T09:05:58.32+0400 [APP/PROC/WEB/0] ERR at tryModuleLoad (module.js:505:12)
2018-04-08T09:05:58.32+0400 [APP/PROC/WEB/0] ERR at Function.Module._load (module.js:497:3)
2018-04-08T09:05:58.32+0400 [APP/PROC/WEB/0] ERR at Module.require (module.js:596:17)
2018-04-08T09:05:58.32+0400 [APP/PROC/WEB/0] ERR at require (internal/module.js:11:18)
2018-04-08T09:05:58.32+0400 [APP/PROC/WEB/0] ERR at Object. (/home/vcap/app/app.js:12:17)
2018-04-08T09:05:58.32+0400 [APP/PROC/WEB/0] ERR at Module._compile (module.js:652:30)
2018-04-08T09:05:58.34+0400 [APP/PROC/WEB/0] OUT Exit status 1
2018-04-08T09:05:58.35+0400 [CELL/SSHD/0] OUT Exit status 0
The PCF specific documentation triggered by the <% else %>
statement on this line breaks my documentation build because I don't have the partial ../../customizing/c2c_pcf_logging
and not even the customizing
directory. Could you please change the else
to something which only applies to PWS or find a more generic solution?
As a general issue, I've been seeing more and more that the official Cloud Foundry documentation contains specific PWS
documentation snippets. I don't think that one vendor should fit the official Cloud Foundry docs so clearly to their needs and would therefore ask PWS developers to also think about other vendors when inserting snippets into the docs that are specific to your platform. It has happened countless times that my build has broken due to such reasons and it would, in my opinion, make much more sense if this remained a documentation exclusively for the product "Cloud Foundry" and wouldn't contain parts specific to PWS. The CF docs should remain vendor agnostic!
We have Bookbinder to combine Cloud Foundry docs and vendor specific docs easily and it should be used to do so instead of some hacky if
-else
statements in the official docs.
Hi,
In previous versions of this page, it used to state
Diego does not support the cf files
command.
Could we please put this back.
https://docs.pivotal.io/pivotalcf/1-12/devguide/deploy-apps/manifest.html#timeout
This section has the following statement which could be wrong:
maximum_health_check_timeout
defaults to 180, but your Cloud Foundry operator can set to any value.
Can we confirm this and update?
I'm able to see how to setup a private domain for a space, but I do not know how to add the certificates or at least I was not able to find them here: https://docs.cloudfoundry.org/devguide/deploy-apps/routes-domains.html
Seems https://github.com/cloudfoundry/cf-docs/blob/a8d0d78fc1fd0b8b762b4ddab6165189566a680a/source/docs/using/deploying-apps/index.html.md#run-multiple-instances-to-increase-availability was lost while moving to docs-dev-guide
It was removed with comment here cloudfoundry/cf-networking-release@ef02f4f
but the new link to the new repo is not found in the doc's page under Administering Container to Container Networking
Right now this page describes very well how to access the trusted system certificates, but only refers to that an administrator will need to add them to the system. It would be great if we could include a link to the doc that describes how an administrator would add these certificates as that's not straight forward to figure out.
using-tasks.html.md.erb
conditionally uses the partial <%= partial '../opsguide/tasks_rec_alloc_pcf' %>
. Since our product_name
is APC
, the template tries to load that partial. I have no idea where the partial should come from or how I should provide it. Furthermore, I think hardcoding an if statement to check for a product_name
of PWS
is wrong because it refers to a specific Cloud Foundry provider which I think must not be hardcoded in the CF docs.
From cloudfoundry/cf-docs#213:
I'm not sure where in the doc set to put it, but we have an entirely undocumented feature that seems to be essentially the same as what is described here: https://devcenter.heroku.com/articles/profiled. I've tried following this guidance from the heroku docs and it looks like it works fine. We need to include this as well.
/cc @cdavisafc
It isn't obvious or documented what to do here:
"To include container metrics in your syslog drain, an operator must first set the scalablesyslog.adapter.metrics_to_syslog_enabled to true"
Can you say exactly how to do this, where from? Is this an Operator or User operation?
Many of the cf CLI sections are written towards users migrating from CLI v5 to v6.
v6 has been out for nearly two years now.
We should rewrite the docs to remove focus on migration:
Uninstall cf CLI v5
section less prominent (http://docs.cloudfoundry.org/devguide/installcf/install-go-cli.html#uninstall-gem)Getting Started with the cf CLI
(the note about Cloud Foundry administrators should be moved to a more appropriate location) (http://docs.cloudfoundry.org/devguide/installcf/whats-new-v6.html)Installation
(already covered in Installing the cf Command Line Interface
) (http://docs.cloudfoundry.org/devguide/installcf/whats-new-v6.html#install)I have an on-Demand redis service on PCF, I am able to follow the instruction up to the point below:
Access Your Service Instance
To establish direct command-line access to your service instance, use the relevant command line tool for that service. This example uses the MySQL command line client to access the MySQL service instance.
$ mysql -u b5136e448be920 -h 0 -p -D ad_b2fca6t49704585d -P 63306
which command line tool I should user for redis? (redis-cli?), what's the syntax for that?
my serviceKey only have the host,password and port info.
Thanks for your help
The instructions at https://github.com/cloudfoundry/docs-dev-guide/blob/6dcf8efdb20d1fa686a7d5ab265bb4c30ca9af99/services/migrate-db.html.md provide an example for starting the rails server which omit the PORT and RAILS_ENV options. Without these, cf push
won't complete properly.
Example of a push log and corrected manifest.yml: https://gist.github.com/pivot-pong-developer/9812974
It seems like the cloud controller is expecting the Rails server to respond to http requests on $PORT, while bundler expects $RAILS_ENV to be set before it installs anything.
Topic "Cloud Controller API Client Libraries" is listed in wrong index "Accessing Services with SSH" on https://docs.run.pivotal.io/devguide/capi/client-libraries.html
Hi. On the Using Application Health Checks page I see the http health check explanation includes:
The configured endpoint must respond within 1 second to be considered healthy.
But lower down, the Health Check Timeouts section says:
In Cloud Foundry, the default timeout is 60 seconds and the maximum configurable timeout is 180 seconds.
Either these are inconsistent, or things are more complex than I understand.
I have a version of the docs which is only addressed at end users of my CF installation. Therefore, I don't want the adminguide in my docs. Can you please put the link to adminguide https://github.com/cloudfoundry/docs-dev-guide/blob/master/services/oms-nozzle.html.md.erb#L33 into a variable so that I can have it point to the official CF docs instead of my own deployed one?
If you check this line in the docs it does not display properly.
I have a version of the docs which is only addressed at end users of my CF installation. Therefore, I don't want the adminguide in my docs. Can you please put the link to adminguide https://github.com/cloudfoundry/docs-dev-guide/blob/master/deploy-apps/cf-networking.html.md.erb#L30 into a variable so that I can have it point to the official CF docs instead of my own deployed one?
The Migrating a Database in Cloud Foundry page currently lists a few methods for migrating app databases. These procedures seem to predate cf tasks
(though the tasks method is mentioned as of 0474c78).
If others agree, I think cf run-task ...
should be the preferred method of running database migrations for all three scenarios listed (once, occasionally, frequently).
This page app-ssh-overview.html
mentions it is possible for the operator to disable it, but doesn't say how.
This page deploy-apps/ssh-apps.html
mentions that an operator can disable access globally but doesn't say how.
The manifest property is cc.allow_app_ssh_access
The documentation states: Authorization Token Grace Period is Minimum 20 Minutes.
Is it supposed to be "Minimum" 20 minutes or "Maximum" 20 Minutes? If the minimum time for the Authorization is 20 Minutes. what is the maximum time?
Thanks
'docs-dev-guide/deploy-apps/large-app-deploy.html.md.erb' says:
Use either the -k flag with cf push or set a disk space allocation value in your manifest.yml file.
However, I can't find any parameter to set a disk space allocation vale in manifest.yml file.
ref. http://docs.cloudfoundry.org/devguide/deploy-apps/manifest.html
So, I guess the sentence should be changed like below:
Use the -k flag with cf push
I have noticed a couple of problems with the Spring services documentation.
The documentation on DATABASE_URL says that
At runtime, CF creates a DATABASE_URL environment variable for every app based on the VCAP_SERVICES environment variable...
But this is not completely accurate. Apps that have no services bound do not have a DATABASE_URL
. It might also be that apps bound to some services also don't have a DATABASE_URL
. We are not completely sure when this variable will be set (otherwise we would have provided suggested text), but we are sure that the current text is not accurate.
Source:
Paired with @blgm
According to http://fbflex.wordpress.com/2014/02/28/spring-boot-jar-cloud-foundry/ the current documentation on deploying Spring Boot Jar apps with Groovy scripts is wrong and does not work.
I have a version of the docs which is only addressed at end users of my CF installation. Therefore, I don't want the adminguide in my docs. Can you please put the link to adminguide https://github.com/cloudfoundry/docs-dev-guide/blob/master/deploy-apps/cf-networking.html.md.erb#L33 into a variable so that I can have it point to the official CF docs instead of my own deployed one?
Can we double check - the docs say 180, and my customer wanted longer. The CF Push allows 600 as a timeout before an error occurs.
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google ❤️ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.