PaaS Operation Manual

Transcription

1 NTT Communications Cloudⁿ PaaS Operation Manual Ver.1.0 Any secondary distribution of this material (distribution, reproduction, provision, etc.) is prohibited. 1

2 Version no. Revision date Revision details Ver.1.0 3/23/2013 Created 1 st draft. 2

3 Table of Contents 1. Introduction P4 1) Service overview 2) Making preparation 2. Preparing for PaaS Service P6 1) Using PaaS Service 2) Launching PaaS web console 3) Installing client software (VMC) 3. Managing/deploying applications P9 1) Deploying applications 2) Changing the application settings 3) Viewing application logs 4) Checking the usage of application resources 4. Using built-in services P20 1) Creating built-in services 2) Binding built-in services 3) Unbinding the built-in service 4) Deleting built-in services 5. Using custom domain URL and SSL P29 1) Using a custom domain 2) Using SSL from a custom domain 6. Others P32 1) Setting alert on application log 2) Updating the applications without affecting the service Appendix 1) About PaaS API P38 3

4 1-1) Overview Cloud n PaaS is a PaaS based on Cloud Foundry, the open PaaS software maintained by Pivotal. Since Cloud n PaaS provides a platform (such as the networks, OSs, and middlewares) to run applications, customers can concentrate on application development without cumbersome platform setup. In addition, Cloud n PaaS allows a customer to scale and monitor applications easily on the web console. The followings are the major features of Cloud n PaaS. It provides a platform, including middlewares, to run applications - A customer can concentrate on application development. Easy to scale out / scale up - Allows a customer to add instances, or change the memory capacity easily. Built-in data services, such as PostgreSQL, MySQL, etc., are offered (for development purpose) - Various services are made available by a single press of a button. Application log management - Logs can be viewed on the web console. This document explains how to manage applications, mainly using the Cloud n PaaS web console. Since Cloud n PaaS is based on Cloud Foundry, a customer can execute most of the Cloud Foundry functionality from the web console. For details about the uses, visit the official website. If you have any questions, please contact us via the Support Portal that can be accessed from the Cloud n Portal. Cloud n PaaS Relational Database Customer Internet Common FW/LB AP Customer s application High speed connection Object Storage Built-In services (for development) Compute

5 1-2) Preparation Make sure you have the followings before using Cloud n PaaS. Devices for Internet connection Check that PCs, modems, and other devices necessary for Internet/intranet connection are in place. Internet connection service Sign up for Internet connection service. e.g.) Any service that provides 24-hour Internet connection, such as OCN Dial Access Service, OCN ADSL Connection Service, Super OCN. - You can use other Internet service providers. - If a proxy server is used in your environment, check that https (port no. 443) is open. Software for browsing the console (browser software) Firefox or later is recommended. Note that some of the displays may not appear correctly with other browsers. [Cloud n ] Service Guide mail Make sure you have Cloud n Service Guide at hand, that was delivered when you have started using Cloud n Service. 5

6 This section explains how to start using PaaS Service ) Using PaaS Service Login to the Cloudⁿ Portal, pose over the PaaS icon in your region, and then click [Signed up] displayed in the box. 2 A pop up appears, indicating the service is starting, and then the PaaS web console screen will be displayed. 6

7 This section explains how to launch the PaaS web console. Once you have signed up the PaaS service, the PaaS web console can be launched directly ) Launching PaaS web console Login to the Cloudⁿ Portal, pose over the PaaS icon in your region, and then click [To console] displayed in the box. 2 The PaaS web console is launched in a new window. 7

8 Cloud n PaaS is based on Cloud Foundry, an opensource PaaS software maintained by Pivotal. You need Cloud Foundry client software to deploy applications to Cloud n PaaS. The most commonly used software are as follows. 1) VMC (command line tool) 2) Spring Tool Suite (STS) or Cloud Foundry extension for Eclipse This manual explains how to install VMC. 2-3) Installing client software Refer to the following if you are using STS or Cloud Foundry extension as client software: 1 Install Ruby How to install, please refer to the following URL: * Note: Ruby is already installed on Mac OS X. 2 Install VMC To install VMC, click [Start] [Ruby p290] [Start Command Prompt with Ruby] in this order. After starting a Ruby console, enter the command below. > gem install vmc v

9 3-1) Deploying applications This section explains how to deploy applications. A Ruby/Sinatra application is used as an example. The following kinds of applications don't run correctly on Cloud n PaaS (and Cloud Foundry-based PaaS environment) Applications that store persistent data into local filesystem (Cloud n Object Storage is a recommended altenative for this purpose). Applications whose instances communicate with each other using IP ports. Applications that need to keep connected with clients, such as WebSocket (to be supported) 1 2 [Start] [Ruby p290] [Start Command Prompt with Ruby] in this order to start Ruby console. Enter the command to connect/login to Cloud n PaaS. > vmc target Successfully targeted to [ > vmc login Attempting login to [ xxxx@cloudnpaas.com Password: ************ Enter the address and password necessary for login in the following format. [Access key ID]'@cloudnpaas.com Password: [Secret key] The access key ID and secret key can be generated/updated in the Cloud n Portal. Refer to Cloud n Portal Operation Manual for details. 9

10 3-1) Deploying applications 3 Use cd command to go to the folder where the application you want to deploy is stored. In the following example, we assume the folder is C: Applications helloworld. > cd C: Applications helloworld In the following example, a simple Sinatra application that renders Hello World! in HTML format will be deployed. Filename: hello.rb require 'sinatra' get '/' do '<html><body>hello World!</body></html>' end Absolute path is a text string that expresses a folder location. You can display an absolute path if you open the folder and select the address bar. It usually starts with C: when the folder is stored in the PC s hard disk. Sinatra is a web application framework based on Ruby. Refer to the following official website for details about Sinatra. Be careful not to include anything other than the files related to the application to deploy in the application folder. It may cause problem on deployment. 10

11 4 3-1) Deploying applications Enter a command "vmc push hello-world" to deploy the application to Cloud n PaaS. A series of dialogs are displayed to collect configurations about the deployment. The following shows an example of the procedure that the sample application is deployed with its name as "hello-world" > vmc push hello-world Would you like to deploy from the current directory? [Yn]: Detected a Sinatra Application, is this correct? [Yn]: Application Deployed URL [hello-world.cloudnpaas.com]: Memory reservation (128M, 256M, 512M, 1G, 2G) [128M]: How many instances? [1]: Bind existing services to 'hello-world'? [yn]: Create services to bind to 'hello-world'? [yn]: Would you like to save this configuration? [yn]: Creating Application: OK Uploading Application: Checking for available resources: OK Packing application: OK Uploading (0K): OK Push Status: OK Staging Application 'hello-world': OK Starting Application 'hello-world': OK For each configuraion dialog with brackets ("[..]"), the content of brackets is the default value. When you just press [Enter] key, the value will be applied to the configuration. You may change memory size and number of instances later. 11

12 5 3-1) Deploying applications After the deployment finished successfully, you may check the status of deployed applications by "vmc apps" command. You may also get detailed information about an application by "vmc stats" command with the application name. > vmc apps Application # Health URLS Services hello-world 1 RUNNING hello-world.cloudnpaas.com >vmc stats hello-world Instance CPU (Cores) Memory (limit) Disk (limit) Uptime % (4) 27.8M (128M) 56.0K (2G) 0d:2h:31m:49s In this example, the "apps" result shows that the application named hello-world is running with "1" instance, given "hello-world.cloudnpaas.com" as an endpoint, and using no services. The "stats" result shows that the instance "0" has been running for approx. 2.5 hours, and currently using resources (CPU, memory, disk) as shown in the table. 6 For web applications, start the web browser, and check if the application is actually running. The following is an example of hello-world application running in the browser, displaying Hello World!. The following address is assigned as the URL of deployed application by default. [Application name].cloudnpass.com 12

13 3-2) Managing deployed application This section explains how to operate a deployed application. You can do the following operation against a deployed application from the Cloud n PaaS web console: Stop Start Delete Change number of instances Change memory capacity per instance If you want to do them using vmc CLI, see the explanations at the end of the section. 1 [Stop] operation stops an application tentatively. You can start it again whenever you want. On the other hand, [Delete] operation deletes an application permanently from the PaaS environment. You have to deploy it again if you want to run it on the environment. Login to the PaaS web console, and click the application you want to operate. Here, hello-world is selected as an example. You can select it by clicking [Applications] menu, then clicking the application in the drop-down list. If the application is stopped, the sign at the lower left area will be [Stopped], as showin in. 13

14 2 3-2) Managing deployed application This console allows you to stop(/start), or delete an application, as well as to change settings, such as number of instances and memory capacity. To change those settigns, click a desired value in [instances] or [instance memory] row. Changing number of instances and memory capacity will restarts all instances of the target application if it is running. When it is stopped, those changes will leave it stopped. If the application is stopped, the button at the upper left corner of the console will be [Start Application], as shown in. 14

15 3 3-2) Managing deployed application When you click the [Stop Application] button, a confirmation dialog as shown in below will appear. the red button if you want really to stop it, or [Cancel] if you don't. There are similar confirmation process for [Delete Application] and [Start Application]. You can also operate a deployed application by using vmc CLI. To stop the application: > vmc stop [application name] To start the application: > vmc start [application name] To Delete the application: > vmc delete [application name] To change the no. of instance: > vmc instances [application name] [no. of instance] To change memory capacity: > vmc mem [application name] [memory capacity (by MB)] To confirm the result of your operaion, just type the commands below. > vmc apps > vmc stats [application name] The sample output of these command are shown in "3-1) Deploying applications", step 5. There is no confirmation dialog in those vmc operatiions. So please be careful when you use it. 15

16 3-3) Viewing application logs This section explains how to see application logs collected. 1 Login to the PaaS web console, and click the application whose logs you want to see. Here, hello-world is selected as an example. You can also select from the application list by clicking [Applications] in the menu. 2 [Logs] in the left menu. 16

17 3 3-3) Viewing application logs A list display appears with the application log files. You can click the file in the list to check the logs inside. You may configure any file in the application folder to be collected as a log by setting the log_paths environment variable via vmc CLI. > vmc env-add [application name] log_paths= [ [log file s path] "] The valueof log_paths is parsed as JSON array. Each log file's path is treated as a relative path from the application folder used on deployment (see Step 3 of 3-1) Deploying applications ). For example, the path can be logs/logfile1.log. To see the current environment variables setting, enter the following command. > vmc env [aplication name] 17

18 3-4) Checking resource usage of application This section explains how to see the resource usages of an application. 1 In the PaaS web console, click the application you want to check. Here, hello-world is used as an example. You can also select from the application list by clicking [Applications] in the menu. 2 [Resource Usage] in the left menu. 18

19 3 3-4) Viewing resource usage of application Recent resource (CPU, memory) usages of an application instance are displayed in percentage. You can select the target instance using the dropdown list, or change the date period using the buttons, in the bar right above the CPU graph. 19

20 4-1) Creating built-in services This section explains how to create a built-in service from the PaaS web console. If you want to do it via vmc CLI, see explanations at the end of the section. 1 Login to the PaaS web console, and click [Services]. 2 [Add Service] shown on the right. 3 Select a service type you want to create from the [Service Type] dropdown list, and put a name into the [Service Name] text field. In this example, a MySQL service named "hello-mysql" will be created. 20

21 4 4-1) Creating built-in services After the service creation is finished, the service ("hello-mysq") appears in the list of created services. You may also create a service with vmc CLI. > vmc create-service [service type] [service name] After the command has been successfully finished, you can confirm the current status by entering the commond below: > vmc services vmc tunnel is a command thet deploys an application named Caldecott. It allows a user tpconnecting to one of the created services. To get more information, please refer to the follwing URL. You may Service use the name following tools when connecting Client service via Caldecott. MySQL PostgreSQL MongoDB Redis mysql psql mongo redis-cli 21

22 4-2) Binding built-in services This section explains how to bind a created service to an application from the PaaS web console. 1 Login to the PaaS web console, click [Services] to show a service list, and click one of the services you want to bind. Here, hello-mysql is used as an example. 2 [Bind to Application]. 22

23 3 4-2) Binding built-in services In the appeared dialog, select an application you want to bind to the service from the pull-down menu. Then click [Bind] button. Here, hello-mysq service will be bound to testapp application. 4 After the bind operation finished, click to show the service again, then you'll see the service is bound to the application. You can also bind the service using vmc CLI. > vmc bind-service [service name] [application name] You can confirm the result of the operation by issueing the following command. > vmc apps 23

24 4-2) Binding built-in services To use bound services from an application, you have to tell the application where the services are (hosts and ports) and who can access the services (users and passwords). Those information is stored in the "VCAP_SERVICES" environment variable in JSON format. You should write the application to refer the information. The following is a sample application that shows the value of "VCAP_SERVICES" environment variable. You may refer it as the same way when you make your application connect to a bound service. require "sinatra" get '/' do ENV['VCAP_SERVICES'] end 24

25 4-3) Unbinding built-in service This section explains how to to unbind a CloudN service from an application via the PaaS web console. 1 Log in to the PaaS web console, click [Services] menu, then click a service you want to unbind. Here, hello-mysql service is used as an example. 2 [Unbind] button at the right of the application name you want to unbind from the service. In the following example, hello-mysql service is unbound from testapp application. 25

26 3 4-3) Unbinding built-in service When the confirmation dialog appears, click [Unbind] to execute the operation indeed. You may also unbind a service using vmc CLI. > vmc unbind-service [service name] [application name] If you enter the following command, you can display the application list and check what services are bound to the respective applications. > vmc apps 26

27 4-4) Deleting built-in services This section explains how to Delete a Cloud n PaaS service from the PaaS web console. 1 Log in to the PaaS web console, click [Services] menu, then click a service bound to an applicaation. Here, hello-mysql service, that is bound to the "hello-world" application, is used as an example.. 2 [Delete Service]. 27

28 3 4-4) Deleting built-in services When the confirmation dialog appears, click [Delete] to execute deletion indeed. Here, hello-mysql service will be deleted. You can also Delete the service using vmc CLI. Enter the command below, and you'll see a list of existing services. Select the number of service you want to delete, then deletion will be executed. > vmc delete-service To make sure that the deleted service no longer exists, enter the following command. > vmc services 28

29 5-1) Using custom domain URL This section explains how to assign a URL of customer's own domain name to an application. 1 2 Login to CloudN PaaS using vmc CLI as written in Step 1 and 2 of "Deploying application" Enter "vmc map" command to assign a custom domain URL to an application. In the following example, is mapped to hello-world application. > vmc map hello-world Successfully mapped url 3 Enter the command "vmc apps" to make sure the URL actually has been assigned. In the following example, " has been added as a URL of the application "hello-world". > vmc apps Application # Health URLS Services hello-world 1 RUNNING hello-world.cloudnpaas.com, Setup DNS for the custom domain of the URL. Set "usarapp.cloudnpaas.com" in CNAME. Specify userapp.cloudnpaas.com as CNAME. About detailed setup procedures, please refer to service guides of DNS service you are using. Be sure to map URL using VMC command before setting up DNS. Otherwise, your domain name becomes available to other users. To stop using a custom domain URL, execute the following command. > vmc unmap [application name] [custom domain URL] 29

30 5-2) Using SSL for custom domain URL This section explains how to use SSL how to use SSL for a custom domain URL. Before you start, please make sure that you can access the application via the custom domain URL assigned to it. 1 Using SSL for a custom domain is an optional service, so additional fee is applied. Obtain an SSL certificate from a certificate authority (CA). Please refer to each certificate authority about detailed procedure to obtain a certificate. Some of major certificate authorities are: VeriSign Japan ( Entrust Japan ( GMOGlobalSign ( You will need an environment to generate a CSR (certificate sigining request). It is recommended to use CloudN Compute for this purpose. 2 Import the certificate to to your CSR generation environment, and export it, including the secret key, to a file 30

31 3 5-2) Using SSL for custom domain URL In Support Portal, issue a ticket to request for SSL setup. Inquiry type: Others Service: Cloud n PaaS Title: SSL setup request Fill in the Inquiry column with the following information, and attach the certificate file (PEM format). Items Explanation FQDN Application type HTTP access PEM file password Enter the relevant FQDN. Specify whether it is for making a new request, or changing/discarding the existing request. Select whether it is allowed or not. When allowed, the URL can be accessed both in http and https. If not allowed, the URL can be accessed only in https (default). Enter the password for attached PEM file. For usage of the Cloud n Support Portal, refer to Support Portal Operation Manual. 4 After the SSL setup is completed, a response to the ticket will be returned. It contains the global IP address for the SSL access. Configure DNS so that the FQDN is resolved to the IP address. We are planning to change the supporting method of SSL in 2013, and customers may be asked to migrate accordingly. Although each global IP address needs to be changed, we will set an overlap period for at least one month, to avoid that the switchover affect the service. Customers only have to change a global IP address resolved to in DNS. 31

32 6-1) Setting alert on application log This section explains how to how to setup alert for specific keywords on application logs. 1 2 Additional fee is applied. In the Cloud n Support Portal, issue a ticket as below to request for log alert setup. Inquiry type: Others Service: Cloud n PaaS Title: Request for log monitoring setup Fill in Log Monitoring Setup Request Form, and attach it to the ticket. The Log Monitoring Setup Request Form is available at the following FAQ page in the Support Portal site.» Top» 7. How to use PaaS ID#: I want to request for application log monitoring setup After the setup is completed, the setup completion notification is sent as a response of the request ticket. To check the setup result, you may make the monitored application output logs that contains the target keyword. To check the setup result, you may make the monitored application to write logs that contains the target keyword. Each notification is sent with 60-second logs after the keyword has been detected. Thus, it may delay at least 60 seconds from the keyword detection to send a notification. 32

33 6-2) Updating application without availability decline With the standard operation of Cloud Foundry, updating an application makes it unavailable a while. This section explains how to update an application (logically) without availability decline. 1 2 Deploy an updated version of the target application with a new name. In the following example, it is named hello-world-2. Using "vmc map" command, assign the updated application the same URL as the application of older version. In the example below, the updated application hello-world-2 is mapped to the existing application's URL hello-world.cloudnpaas.com > vmc map hello-world-2 hello-world.cloudnpaas.com Successfully mapped url 3 Delete, or stop the old application. 33

34 (Appendix) About PaaS API In CloudN PaaS, a set of REST API allows you to operate an application and view its status. You may use the extended CloudN PaaS API in addition to the Cloud Foundry API. The endpoint is All the response are in JSON format Use the same user ID / password as vmc login when you get a certificate token Category Roles HTTP Method URL Cloud Foundry Standard Obtain PaaS information GET /info Obtain built-in service information in PaaS GET /info/services Obtain runtime information supported in PaaS GET /info/runtimes Obtain user information GET /users/:user_id Update user password PUT /users/:user_id Obtain certificate token POST /users/:user_id/tokens Obtain a list of user applications GET /apps Deploy user application POST /apps Obtain user application information GET /apps/:appname Update user application PUT /apps/:appname Delete user application DELETE /apps/:appname Obtain instance information of user application GET /apps/:appname/instances Obtain statistics of user application GET /apps/:appname/stats Obtain crush information of user application GET /apps/:appname/crashes Obtain a file list (by instance) Obtain file content (by instance) GET GET /apps/:appname/instances/:insta nce_id/files /apps/:appname/instances/:insta nce_id/files/*path Obtain a log file list GET /apps/:appname/logs Clound n PaaS extended Obtain log file content GET /apps/:appname/logs/*path For details about API specifications, refer to the PaaS API manual. 34