onos-create-app으로 새 ONOS 애플리케이션 만들기

이 글에서는 onos-create-app으로 템플릿 애플리케이션을 생성하여, 이를 기반으로 새 ONOS 애플리케이션을 만드는 방법을 다룬다.

ONOS 애플리케이션 개발 환경 세팅

템플릿 애플리케이션을 생성하기 전에, ONOS 애플리케이션 개발 환경을 세팅한다.

먼저, ~/.bashrc에서 Java 관련 환경 변수가 올바르게 설정되었는지 다시 확인한다. 템플릿 애플리케이션의 target ONOS 버전에 따라서 애플리케이션 개발 시 사용하는 Java 버전이 달라지기 때문이다. ONOS archetype 2.2.x 버전부터는 Java 11을 사용하여 ONOS 애플리케이션을 빌드하도록 강제되어 있다. 그 아래 버전까지는 Java 8을 사용하여 빌드한다.

Archetype 관련 세팅을 진행한다. Target ONOS 버전에 따라 세팅 방법이 다르다.

• 생각하고 있는 target ONOS 버전이 Maven 중앙 저장소에 존재하는 경우, “ONOS 버전 관련 환경 변수 설정” 문단으로 바로 넘어간다.
• 생각하고 있는 target ONOS 버전이 Maven 중앙 저장소에 존재하지 않는 경우 문단을 건너뛰지 않고 진행한다.

로컬 저장소에 ONOS Artifact 직접 설치

생각하고 있는 target ONOS 버전이 Maven 중앙 저장소에 존재하지 않는 경우, 템플릿 애플리케이션을 생성하기 전에 로컬 저장소에 ONOS artifact를 직접 설치해야 한다. 단, Maven으로 빌드하는 ONOS 1.7 버전까지는 빌드하면서 함께 설치되므로 이 과정을 건너뛴다. (Buck으로 빌드한 ONOS 1.6-1.7 버전을 위한 방법은 공식적인 툴이 없으므로 번거로울 수 있다. 그 방법을 여기서 소개하지는 않겠다.)

$ONOS_ROOT/tools/package/archetypes 디렉터리로 이동하여 ONOS archetype을 Maven 로컬 저장소에 설치한다.

$ cd $ONOS_ROOT/tools/package/archetypes
$ mvn clean install

Maven 로컬 저장소에 설치된 onos-archetypes의 버전을 확인하여 기억해 둔다. 이 예제에서는 2.3.0-rc2이다.

$ ls ~/.m2/repository/org/onosproject/onos-archetypes
2.3.0-rc2  maven-metadata-local.xml

이제 ONOS 버전에 따라 ONOS artifact를 Maven 로컬 저장소에 설치한다.

ONOS 1.14 이상 버전에서 ONOS Artifact 설치

먼저 onos-publish를 실행하는 데 필요한, Python 2의 requests 모듈을 설치한다.

$ sudo apt-get install python-pip
$ sudo pip install requests

$ONOS_ROOT 디렉터리로 이동하여 onos-publish -l로 ONOS 라이브러리를 Maven 로컬 저장소에 설치한다.

$ cd $ONOS_ROOT
$ onos-publish -l

ONOS 1.8-1.13 버전에서 ONOS Artifact 설치

$ONOS_ROOT 디렉터리로 이동하여 onos-buck-publish-local로 ONOS 라이브러리를 Maven 로컬 저장소에 설치한다.

$ cd $ONOS_ROOT
$ onos-buck-publish-local

ONOS 버전 관련 환경 변수 설정

템플릿 애플리케이션을 생성하기 전에 애플리케이션의 target ONOS 버전을 지정한다. 생성할 템플릿 애플리케이션의 버전을 따로 지정하지 않으면 무조건 최신 버전의 ONOS를 위한 템플릿 애플리케이션을 생성한다. 이 경우 호환되지 않는 버전에서는 빌드나 구동에 실패할 수 있다.

~/.bashrc를 열어서, target ONOS 버전에 맞게 아래 형태의 내용을 추가한다. “로컬 저장소에 ONOS Artifact 직접 설치” 문단을 진행했다면, 그때 기억해 둔 onos-archetypes의 버전을 사용한다. 이 예제에서는 ONOS_POM_VERSION을 "2.3.0-rc2"로 설정한다.

export ONOS_POM_VERSION="2.3.0-rc2"

터미널 창을 다시 열거나 source ~/.bashrc를 실행한다. 이제 “템플릿 애플리케이션 생성” 문단으로 넘어간다.

---

템플릿 애플리케이션 생성

onos-create-app으로 ONOS 템플릿 애플리케이션 Maven 모듈을 생성한다. 인터넷에 연결되어 있어야 한다. 중간중간 필요한 dependency를 받는 과정이 추가될 수 있다. (이 단계에서 archtype 관련 오류가 발생하면서 진행이 되지 않으면, 먼저 터미널 창을 다시 열어서 시도해 보고, 다른 버전을 선택하거나, 앞의 “로컬 저장소에 ONOS Artifact 직접 설치” 문단 부분부터 다시 진행한다.)

$ onos-create-app
[INFO] Scanning for projects...
[INFO]
[INFO] ------------------< org.apache.maven:standalone-pom >-------------------
[INFO] Building Maven Stub Project (No POM) 1
[INFO] --------------------------------[ pom ]---------------------------------
[INFO]
[INFO] >>> maven-archetype-plugin:3.1.2:generate (default-cli) > generate-sources @ standalone-pom >>>
[INFO]
[INFO] <<< maven-archetype-plugin:3.1.2:generate (default-cli) < generate-sources @ standalone-pom <<<
[INFO]
[INFO]
[INFO] --- maven-archetype-plugin:3.1.2:generate (default-cli) @ standalone-pom ---
[INFO] Generating project in Interactive mode
[INFO] Archetype [org.onosproject:onos-bundle-archetype:2.3.0-rc2] found in catalog local
Define value for property 'groupId':

진행 중간에 “Define value for property 'xxx':”가 출력되고 입력을 기다리면, 아래 예제와 같이 원하는 내용으로 채운다. 기본값이 있는 property를 입력할 때 아무 내용도 입력하지 않고 Enter를 누르면 기본값이 들어간다.

Property	기본값	예제 입력
groupId	없음	org.example
artifactId	없음	myapp
version	1.0-SNAPSHOT	입력 안 함(기본값 사용)
package	(groupId)	org.example.myapp

...
Define value for property 'groupId': org.example
Define value for property 'artifactId': myapp
Define value for property 'version' 1.0-SNAPSHOT: :
Define value for property 'package' org.example: : org.example.myapp
...

이제 앞의 입력을 확인한다. 출력된 내용이 맞다면 Enter를 눌러 계속 진행한다. 잘못 입력했다면 Y, y, whitespace가 아닌 다른 내용을 입력하여 property를 입력하는 단계로 돌아가거나, Ctrl+C를 눌러 취소하고 onos-create-app을 다시 실행한다.

...
[INFO] Using property: onosVersion = 2.3.0-rc2
Confirm properties configuration:
groupId: org.example
artifactId: myapp
version: 1.0-SNAPSHOT
package: org.example.myapp
onosVersion: 2.3.0-rc2
 Y: :
[INFO] ----------------------------------------------------------------------------
[INFO] Using following parameters for creating project from Archetype: onos-bundle-archetype:2.3.0-rc2
[INFO] ----------------------------------------------------------------------------
[INFO] Parameter: groupId, Value: org.example
[INFO] Parameter: artifactId, Value: myapp
[INFO] Parameter: version, Value: 1.0-SNAPSHOT
[INFO] Parameter: package, Value: org.example.myapp
[INFO] Parameter: packageInPathFormat, Value: org/example/myapp
[INFO] Parameter: package, Value: org.example.myapp
[INFO] Parameter: groupId, Value: org.example
[INFO] Parameter: artifactId, Value: myapp
[INFO] Parameter: onosVersion, Value: 2.3.0-rc2
[INFO] Parameter: version, Value: 1.0-SNAPSHOT
[INFO] Project created from Archetype in dir: /home/username/myapp
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  31.692 s
[INFO] Finished at: 2020-01-22T05:16:23+09:00
[INFO] ------------------------------------------------------------------------

이제 artifactId에 입력한 이름으로 Maven 모듈 디렉터리가 하나 만들어졌다. 이제 IntelliJ IDEA, Eclipse 등의 IDE에서 이 모듈을 import하여 사용할 수 있다. 앞의 예제에서 만들어진 ONOS 템플릿 애플리케이션 Maven 모듈의 구조는 다음과 같다.

myapp
├── pom.xml
└── src
    ├── main
    │   └── java
    │       └── org
    │           └── example
    │               └── myapp
    │                   ├── AppComponent.java
    │                   ├── package-info.java
    │                   └── SomeInterface.java
    └── test
        └── java
            └── org
                └── example
                    └── myapp
                        └── AppComponentTest.java

---

애플리케이션 작성

ONOS 애플리케이션 정보 작성

모듈 루트의 pom.xml을 열어서 ONOS 애플리케이션의 정보를 작성한다.

<properties>...</properties> 부분의 주석을 해제하고 내용을 채운다. 이 부분은 버전에 따라 내용이 다를 수 있다.

    <properties>
        <onos.app.name>org.example.myapp</onos.app.name>
        <onos.app.title>Example App</onos.app.title>
        <onos.app.origin>leeye51456</onos.app.origin>
        <onos.app.category>default</onos.app.category>
        <onos.app.url>http://onosproject.org</onos.app.url>
        <onos.app.readme>ONOS OSGi bundle archetype.</onos.app.readme>
    </properties>

<dependencies>...</dependencies> 부분에는 ONOS 애플리케이션을 빌드하기 위한 기본적으로 필요한 dependency가 포함되어 있다. 이 부분에 추가로 필요한 dependency를 추가한다.

ONOS 애플리케이션 코드 작성

ONOS 애플리케이션 코드를 작성한다. 이 예제는 ONOS 2.3.0-rc2 버전을 위한 템플릿 애플리케이션의 일부를 삭제하여 만든, activate/deactivate 시 “Started”/“Stopped”라는 내용의 로그를 info 레벨로 출력하는 코드이다.

// myapp/src/main/java/org/example/myapp/AppComponent.java
package org.example.myapp;

import org.osgi.service.component.annotations.Activate;
import org.osgi.service.component.annotations.Component;
import org.osgi.service.component.annotations.Deactivate;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

@Component(immediate = true)
public class AppComponent {

    private final Logger log = LoggerFactory.getLogger(getClass());

    @Activate
    protected void activate() {
        log.info("Started");
    }

    @Deactivate
    protected void deactivate() {
        log.info("Stopped");
    }

}

// myapp/src/test/java/org/example/myapp/AppComponentTest.java
package org.example.myapp;

import org.junit.After;
import org.junit.Before;
import org.junit.Test;

public class AppComponentTest {

    private AppComponent component;

    @Before
    public void setUp() {
        component = new AppComponent();
        component.activate();
    }

    @After
    public void tearDown() {
        component.deactivate();
    }

    @Test
    public void basics() {
    }

}

---

ONOS 애플리케이션 빌드, 설치, 활성화

ONOS 애플리케이션 빌드

모듈 디렉터리에서 mvn clean install로 애플리케이션을 빌드할 수 있다. 여기서 install은 Maven lifecycle 중 패키지를 Maven 로컬 저장소에 설치하는 phase를 가리키며, 빌드한 애플리케이션을 ONOS에 설치한다는 의미가 아니다.

$ mvn clean install
[INFO] Scanning for projects...
[INFO]
[INFO] -------------------------< org.example:myapp >--------------------------
[INFO] Building myapp 1.0-SNAPSHOT
...
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  02:21 min
[INFO] Finished at: 2020-01-22T05:25:12+09:00
[INFO] ------------------------------------------------------------------------

Maven으로 빌드 후 모듈 디렉터리에 target이라는 디렉터리가 생성된다. 이 디렉터리 아래에 oar(ONOS App aRchive) 파일이 생성된다.

myapp
├── pom.xml
├── src
│   └── ...
└── target
    ├── myapp-1.0-SNAPSHOT.oar
    └── ...

ONOS 애플리케이션 설치

ONOS에서는 ONOS 애플리케이션 관리와 관련된 제어를 위해 onos-app이라는 툴을 제공한다. 이 툴로 다음과 같이 실행 중인 ONOS에 애플리케이션을 설치할 수 있다.

$ onos-app localhost install target/myapp-1.0-SNAPSHOT.oar

install 대신 reinstall을 입력하면 애플리케이션이 이미 설치되어 있는 경우 재설치를 진행한다. (re)install 뒤에 !를 붙이면 설치 후 바로 활성화한다.

ONOS 애플리케이션 활성화 및 비활성화

활성화

ONOS CLI에서 app activate <onos.app.name> 명령어로 ONOS 애플리케이션을 활성화하여 구동할 수 있다. 활성화된 애플리케이션 목록은 ONOS CLI에서 apps -s -a 명령어로 확인할 수 있다.

username@root > app activate org.example.myapp
Activated org.example.myapp
username@root > apps -s -a
*  13 org.onosproject.optical-model        2.3.0.rc2 Optical Network Model
*  34 org.onosproject.drivers              2.3.0.rc2 Default Drivers
*  59 org.onosproject.hostprovider         2.3.0.rc2 Host Location Provider
*  60 org.onosproject.lldpprovider         2.3.0.rc2 LLDP Link Provider
*  61 org.onosproject.openflow-base        2.3.0.rc2 OpenFlow Base Provider
*  62 org.onosproject.openflow             2.3.0.rc2 OpenFlow Provider Suite
* 123 org.onosproject.gui2                 2.3.0.rc2 ONOS GUI2
* 192 org.example.myapp                    1.0.SNAPSHOT Example App

onos-app 툴을 이용하여 onos-app <ip> activate <onos.app.name>으로도 설치된 ONOS 애플리케이션을 활성화할 수 있다.

$ onos-app localhost activate org.example.myapp

이 예제에서 작성한 애플리케이션이 활성화되면 ONOS에는 다음과 같은 로그가 남는다.

2020-01-22T05:31:47,470 | INFO  | features-3-thread-1 | AppComponent                     | 209 - org.example.myapp - 1.0.0.SNAPSHOT | Started

비활성화

ONOS 애플리케이션 활성화 방법과 비슷하게, ONOS CLI에서 app deactivate <onos.app.name> 명령어로 ONOS 애플리케이션을 비활성화할 수 있다.

username@root > app deactivate org.example.myapp
Deactivated org.example.myapp

onos-app 툴을 이용하여 onos-app <ip> deactivate <onos.app.name>으로도 활성화된 ONOS 애플리케이션을 비활성화할 수 있다.

$ onos-app localhost deactivate org.example.myapp

이 예제에서 작성한 애플리케이션이 비활성화되면 ONOS에는 다음과 같은 로그가 남는다.

2020-01-22T05:32:50,886 | INFO  | features-3-thread-1 | AppComponent                     | 209 - org.example.myapp - 1.0.0.SNAPSHOT | Stopped

참고: onos-app 툴 사용법

$ onos-app <ip> <command> <param>

<command>	<param>	동작
install	oar 파일 경로	애플리케이션 설치
install!	oar 파일 경로	애플리케이션 설치 후 활성화
reinstall	oar 파일 경로	애플리케이션 재설치
reinstall!	oar 파일 경로	애플리케이션 재설치 후 활성화
activate	<onos.app.name>	애플리케이션 활성화
deactivate	<onos.app.name>	애플리케이션 비활성화

더 찾아보기

• ONOS Wiki: Template Application Tutorial
• Maven
  • Maven lifecycle
  • pom.xml 구조
• OSGi annotations
• JUnit
• SLF4J