aboutsummaryrefslogtreecommitdiffstats
path: root/ci/README.rst
blob: dc860c003da6acb90298a603162313161548b1ad (plain) 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102

.. This work is licensed under a Creative Commons Attribution 4.0 International License.
.. SPDX-License-Identifier: CC-BY-4.0
.. (c) 2017 Ericsson AB, Mirantis Inc., Enea Software AB and others.

Abstract
========
The fuel/ci directory holds all Fuel@OPNFV programatic abstractions for
the OPNFV community release and continous integration pipeline.
There is now only one Fuel@OPNFV autonomous script for this, complying to the
OPNFV CI pipeline guideline:
 - deploy.sh

USAGE
=====
For usage information of the CI/CD scripts, please run:

    .. code-block:: bash

        $ ./deploy.sh -h

Details on the CI/CD deployment framework
=========================================

Overview and purpose
--------------------
The CI/CD deployment script relies on a configuration structure, providing base
installer configuration (part of fuel repo: mcp/config), per POD specific
configuration (part of a separate classified POD configuration repo: securedlab
and deployment scenario configuration (part of fuel repo: mcp/config/scenario).

- The base installer configuration resembles the least common denominator of all
  HW/POD environment and deployment scenarios. These configurations are
  normally carried by the the installer projects in this case (Fuel@OPNFV).
- Per POD specific configuration specifies POD unique parameters, the POD
  parameter possible to alter is governed by the Fuel@OPNFV project.
- Deployment scenario configuration - provides a high level, POD/HW environment
  independent scenario configuration for a specifiv deployment. It defines what
  features shall be deployed - as well needed overrides of the base
  installer, POD/HW environment configurations. Objects allowed to override
  are governed by the Fuel@OPNFV project.

Executing a deployment
----------------------
deploy.sh must be executed locally at the target lab/pod/jumpserver
A configuration structure must be provided - see the section below.
It is straight forward to execute a deployment task - as an example:

    .. code-block:: bash

        $ sudo deploy.sh -b file:///home/jenkins/config
                         -l lf -p pod2 -s os-nosdn-nofeature-ha

-b and -i arguments should be expressed in URI style (eg: file://...
or http://...). The resources can thus be local or remote.

Configuration repository structure
----------------------------------
The CI deployment engine relies on a configuration directory/file structure
pointed to by the -b option described above.
Normally this points to the secure classified OPNFV securedlab repo to which
only jenkins and andmins have access to, but you may point to any local or
remote strcture fullfilling the diectory/file structure below.
The reason that this configuration structure needs to be secure/hidden
is that there are security sensitive information in the various configuration
files.

FIXME: Below information is out of date and should be refreshed after PDF
support is fully implemented.

A local stripped version of this configuration structure with virtual
deployment configurations also exist under build/config/.
Following configuration directory and file structure should adheare to:

    .. code-block:: bash

        TOP
        !
        +---- labs
               !
               +---- lab-name-1
               !        !
               !        +---- pod-name-1
               !        !        !
               !        !        +---- fuel
               !        !               !
               !        !               +---- config
               !        !                       !
               !        !                       +---- dea-pod-override.yaml
               !        !                       !
               !        !                       +---- dha.yaml
               !        !
               !        +---- pod-name-2
               !                 !
               !
               +---- lab-name-2
               !        !


Creating a deployment scenario
------------------------------
Please find `mcp/config/README.rst` for instructions on how to create a new
deployment scenario.
s="cm"> * This provides access to useful OS routines for the sandbox architecture. * They are kept in a separate file so we can include system headers. * * Copyright (c) 2011 The Chromium OS Authors. * SPDX-License-Identifier: GPL-2.0+ */ #ifndef __OS_H__ #define __OS_H__ #include <linux/types.h> struct sandbox_state; /** * Access to the OS read() system call * * \param fd File descriptor as returned by os_open() * \param buf Buffer to place data * \param count Number of bytes to read * \return number of bytes read, or -1 on error */ ssize_t os_read(int fd, void *buf, size_t count); /** * Access to the OS read() system call with non-blocking access * * \param fd File descriptor as returned by os_open() * \param buf Buffer to place data * \param count Number of bytes to read * \return number of bytes read, or -1 on error */ ssize_t os_read_no_block(int fd, void *buf, size_t count); /** * Access to the OS write() system call * * \param fd File descriptor as returned by os_open() * \param buf Buffer containing data to write * \param count Number of bytes to write * \return number of bytes written, or -1 on error */ ssize_t os_write(int fd, const void *buf, size_t count); /** * Access to the OS lseek() system call * * \param fd File descriptor as returned by os_open() * \param offset File offset (based on whence) * \param whence Position offset is relative to (see below) * \return new file offset */ off_t os_lseek(int fd, off_t offset, int whence); /* Defines for "whence" in os_lseek() */ #define OS_SEEK_SET 0 #define OS_SEEK_CUR 1 #define OS_SEEK_END 2 /** * Access to the OS open() system call * * \param pathname Pathname of file to open * \param flags Flags, like O_RDONLY, O_RDWR * \return file descriptor, or -1 on error */ int os_open(const char *pathname, int flags); #define OS_O_RDONLY 0 #define OS_O_WRONLY 1 #define OS_O_RDWR 2 #define OS_O_MASK 3 /* Mask for read/write flags */ #define OS_O_CREAT 0100 /** * Access to the OS close() system call * * \param fd File descriptor to close * \return 0 on success, -1 on error */ int os_close(int fd); /** * Access to the OS unlink() system call * * \param pathname Path of file to delete * \return 0 for success, other for error */ int os_unlink(const char *pathname); /** * Access to the OS exit() system call * * This exits with the supplied return code, which should be 0 to indicate * success. * * @param exit_code exit code for U-Boot */ void os_exit(int exit_code) __attribute__((noreturn)); /** * Put tty into raw mode to mimic serial console better * * @param fd File descriptor of stdin (normally 0) * @param allow_sigs Allow Ctrl-C, Ctrl-Z to generate signals rather than * be handled by U-Boot */ void os_tty_raw(int fd, bool allow_sigs); /** * Acquires some memory from the underlying os. * * \param length Number of bytes to be allocated * \return Pointer to length bytes or NULL on error */ void *os_malloc(size_t length); /** * Free memory previous allocated with os_malloc()/os_realloc() * * This returns the memory to the OS. * * \param ptr Pointer to memory block to free */ void os_free(void *ptr); /** * Reallocate previously-allocated memory to increase/decrease space * * This works in a similar way to the C library realloc() function. If * length is 0, then ptr is freed. Otherwise the space used by ptr is * expanded or reduced depending on whether length is larger or smaller * than before. * * If ptr is NULL, then this is similar to calling os_malloc(). * * This function may need to move the memory block to make room for any * extra space, in which case the new pointer is returned. * * \param ptr Pointer to memory block to reallocate * \param length New length for memory block * \return pointer to new memory block, or NULL on failure or if length * is 0. */ void *os_realloc(void *ptr, size_t length); /** * Access to the usleep function of the os * * \param usec Time to sleep in micro seconds */ void os_usleep(unsigned long usec); /** * Gets a monotonic increasing number of nano seconds from the OS * * \return A monotonic increasing time scaled in nano seconds */ uint64_t os_get_nsec(void); /** * Parse arguments and update sandbox state. * * @param state Sandbox state to update * @param argc Argument count * @param argv Argument vector * @return 0 if ok, and program should continue; * 1 if ok, but program should stop; * -1 on error: program should terminate. */ int os_parse_args(struct sandbox_state *state, int argc, char *argv[]); /* * Types of directory entry that we support. See also os_dirent_typename in * the C file. */ enum os_dirent_t { OS_FILET_REG, /* Regular file */ OS_FILET_LNK, /* Symbolic link */ OS_FILET_DIR, /* Directory */ OS_FILET_UNKNOWN, /* Something else */ OS_FILET_COUNT, }; /** A directory entry node, containing information about a single dirent */ struct os_dirent_node { struct os_dirent_node *next; /* Pointer to next node, or NULL */ ulong size; /* Size of file in bytes */ enum os_dirent_t type; /* Type of entry */ char name[0]; /* Name of entry */ }; /** * Get a directionry listing * * This allocates and returns a linked list containing the directory listing. * * @param dirname Directory to examine * @param headp Returns pointer to head of linked list, or NULL if none * @return 0 if ok, -ve on error */ int os_dirent_ls(const char *dirname, struct os_dirent_node **headp); /** * Get the name of a directory entry type * * @param type Type to cehck * @return string containing the name of that type, or "???" if none/invalid */ const char *os_dirent_get_typename(enum os_dirent_t type); /** * Get the size of a file * * @param fname Filename to check * @return size of file, or -1 if an error ocurred */ ssize_t os_get_filesize(const char *fname); /** * Write a character to the controlling OS terminal * * This bypasses the U-Boot console support and writes directly to the OS * stdout file descriptor. * * @param ch Character to write */ void os_putc(int ch); /** * Write a string to the controlling OS terminal * * This bypasses the U-Boot console support and writes directly to the OS * stdout file descriptor. * * @param str String to write (note that \n is not appended) */ void os_puts(const char *str); /** * Write the sandbox RAM buffer to a existing file * * @param fname Filename to write memory to (simple binary format) * @return 0 if OK, -ve on error */ int os_write_ram_buf(const char *fname); /** * Read the sandbox RAM buffer from an existing file * * @param fname Filename containing memory (simple binary format) * @return 0 if OK, -ve on error */ int os_read_ram_buf(const char *fname); /** * Jump to a new executable image * * This uses exec() to run a new executable image, after putting it in a * temporary file. The same arguments and environment are passed to this * new image, with the addition of: * * -j <filename> Specifies the filename the image was written to. The * calling image may want to delete this at some point. * -m <filename> Specifies the file containing the sandbox memory * (ram_buf) from this image, so that the new image can * have access to this. It also means that the original * memory filename passed to U-Boot will be left intact. * * @param dest Buffer containing executable image * @param size Size of buffer */ int os_jump_to_image(const void *dest, int size); #endif