Background: This relates to the Bluemix CLI for IBM Cloud (which was once called Bluemix, hence the tool name). IBM Cloud is a pretty powerful beast and so the related tools can sometimes be confusing, especially to newcomers. Here's my handy guide for working with it.
APIs and Regions
Before you log in, tell
bx which region you want to log into by setting the API. When the region isn't set, the tool will often tell you
No api endpoint set. Use 'bx api' to set an endpoint, so let's do that. If you don't have an API set, then the
bx api command will show you a list of choices:
$ bx api No api endpoint set. Use 'bx api' to set an endpoint Available public api endpoints are: Region API Endpoint eu-de https://api.eu-de.bluemix.net au-syd https://api.au-syd.bluemix.net us-south https://api.ng.bluemix.net eu-gb https://api.eu-gb.bluemix.net
Set the API by using one of the URLs shown:
$ bx api https://api.eu-gb.bluemix.net Setting api endpoint to https://api.eu-gb.bluemix.net... OK API endpoint: https://api.eu-gb.bluemix.net (CF API version: 2.92.0) Not logged in. Use 'bx login' to log in.
However if the API is already set and you want to change it, the
bx regions command will show that list again
$ bx regions Listing Bluemix regions... Name Geolocation Customer Deployment Domain CF API Endpoint Type eu-de Germany IBM Production eu-de.bluemix.net https://api.eu-de.bluemix.net public au-syd Sydney IBM Production au-syd.bluemix.net https://api.au-syd.bluemix.net public us-south US South IBM Production ng.bluemix.net https://api.ng.bluemix.net public eu-gb United Kingdom IBM Production eu-gb.bluemix.net https://api.eu-gb.bluemix.net public
Now you can switch the API as before. If you work with IBM Cloud in multiple geographies, as I do (I'm in the UK but my team is in the US), you'll get to know this end of the tool very well indeed!
Option 1: type
bx login and you will be prompted for your login credentials (username/email, password). If you have access to more than one account then you'll be prompted to pick which one you need, or you can supply this information on the command line.
There's a bunch of other things that you might like to do with this command as well, such as:
* as I just mentioned: supply your Account ID with
-c (more on accounts later)
* use an API Key rather than having to type your credentials (also more on this later)
* specify the organisation and space to target with
-s respectively (recommended)
If you use a federated login (IBM-ers, this includes you) then use
bx login --sso instead. It will give you a URL to visit to get a one-time access code to log in with.
Targeting a Workspace
For some IBM Cloud features, you'll be in a particular workspace. This is a combination of region, account, organization and space and you can switch between these using the
bx target command. Run it by itself to check where you're currently pointing to. You won't be able to see things in other spaces when you're not targeting that space.
Interactively choose target in this region/account this is helpful if you don't know exactly the words to type!
bx target --cf presents a list of organizations and spaces in this current account/region for you to choose from. You can't script it but it's quite user-friendly!
Change regions with
bx target -r eu-gb or whichever region you want. See the options with
Change accounts with
bx target -c [account ID], but get the account ID from the output of
bx account list (look at the final section of this blog post for a helper script for this)
Change organizations and spaces with
bx target -o [org] -s [space]. Find out the possibilities with
bx account orgs and
bx account spaces
Combine all of the above with
bx -r eu-gb -c [accountID] --cf and get prompted for the organisation and space info, or replace
Generate an API Key
The access control features are a big topic but knowing how to create an API is useful here. You can give the token as a secret to your deployment script, or even set it in your environment so you can log in more easily. To generate an API key:
bx iam api-key-create
With the key then you can login with
bx login --apikey [key].
Cloud Foundry Tools and The Bluemix CLI
Previously, IBM Cloud was accessed by the Cloud Foundry commandline tool,
cf and I wrote a cheatsheet for that last year. If you're familiar with the
cf tools then there are a few adjustments to make to your existing commands/scripts but it shouldn't be too weird:
bx instead of
cf for these commands:
login, logout, api, target
* for everything else, use
bx cf instead of just
Some existing Cloud Foundry integrations will work if you supply a username of
apikey and a valid API key as a password.
Lorna's Script Collection
Here's a quick dump of the helper scripts that I use to keep me moving quickly with IBM Cloud.
Federated User Login - I have one of these per region, with the API keys and one-time token URLs set as appropriate. You could probably use API keys here as well.
#!/bin/bash bluemix logout google-chrome https://iam.eu-gb.bluemix.net/identity/passcode bluemix api https://api.eu-gb.bluemix.net bluemix login --sso
This opens the token page in chrome (it's slow, so start this first!) so you can switch to and copy it, and sets the API, then starts the login process
Switching accounts - quick and dirty script, will basically pick the first account it finds that matches whatever argument you supplied. e.g.
#!/bin/bash bx account list | tail -n +4 | grep -i $1 | cut -d ' ' -f 1 | xargs bx target -c
Do you have favourite tricks to share? I'd love to hear them!